Skip to main content
Glama
GrowSurf MCP Server

GrowSurf MCP Server

Official

Record Affiliate Refund or Chargeback

growsurf_refund_transaction
DestructiveIdempotent

Records refunds, partial refunds, and chargebacks for a prior affiliate transaction and adjusts the referrer's commission in GrowSurf without sending a refund through the payment provider.

Instructions

Record a refund, partial refund, or chargeback for a previously recorded affiliate transaction in GrowSurf and reverse or adjust the referrer's commission. This records the amendment without sending a refund through the payment provider. Requires the same transaction identifier as the original sale. Omitted amountRefunded means a full refund. Already-paid commissions are not clawed back and are recorded for tax only. Targets campaignId if supplied, otherwise GROWSURF_CAMPAIGN_ID.

Input Schema

NameRequiredDescriptionDefault
amountNo
orderIdNo
chargeIdNo
currencyNo
refundIdNoStable per-refund identifier. Required when canceling a refund or changing the refunded total after a cancellation. Reuse the original refund's identifier for its cancellation. An amendment without enough refund identity returns `409` without applying the cancellation. Newly observed higher cumulative refunds and incomplete coverage are retained for reconciliation.
testModeNoOriginal payment mode: `true` for test or `false` for live. Requires `paymentProvider`.
invoiceIdNo
paymentIdNo
campaignIdYesTarget program id for this call: the `id` returned by `growsurf_list_campaigns`, not the program name or a share URL. Defaults to GROWSURF_CAMPAIGN_ID when omitted. Program IDs also identify newly created programs without restarting the server.
externalIdNo
descriptionNo
refundAmountNoPositive amount for this individual refund, no greater than the sale amount, in the sale currency's minor unit. Send it with `refundId` on each original refund to support cancellations and out-of-order amendments. The amount for a given `refundId` cannot change. A cancellation can omit it when the original amount is already recorded. Incomplete refund history returns `409` without applying the cancellation. Newly observed higher cumulative refunds and incomplete coverage are retained for reconciliation.
refundStatusNoRefund status. Send `canceled` with the original `refundId` to cancel that refund.
amendmentTypeNoDefaults to `REFUND`, which covers full refunds, partial refunds, and refund cancellations. `CHARGEBACK` is always a full reversal.
participantIdNo
transactionIdNo
amountRefundedNoTotal refunded so far, in the currency's minor unit. Omit for a full refund. For a partial refund send the running total, not the amount of this one refund. Required when `refundStatus` is `canceled`: send the total that stays refunded after the cancellation (`0` when none remain).
paymentIntentIdNo
paymentProviderNoConnected provider for the original payment. Requires its `transactionId` and `testMode`. This amends GrowSurf records without sending a refund through the provider.
participantEmailNo
refundHistoryCompleteNoSet true only after reconciling and recording every original refundId and refundAmount, including refunds later canceled. This confirmation resolves previously incomplete history. Omit during ordinary delivery. Replaying an old confirmation cannot resolve a later gap; confirm a newly reconciled refund or complete provider list.

Output Schema

NameRequiredDescriptionDefault
deletedNoPending commissions deleted by the amendment.
matchedNoCommissions found for the provided identifiers.
messageNoHuman-readable result message.
successNo`true` when the amendment was processed; `false` when no matching transaction was found.
adjustedNoCommissions partially adjusted.
notFoundNoPresent and `true` when no commission matched the provided identifiers.
reversedNoCommissions reversed (set to zero amount).
amendmentTypeNoAmendment type that was processed.
matchingCommissionIdsNoCommission ids that matched the submitted identifiers.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.19.34
    • changedInput schema / properties / amountRefunded / description
      Previous value: -"Total refunded so far, in the currency's minor unit. Omit for a full refund. For a partial refund send the running total, not the amount of this one refund."New value: +"Total refunded so far, in the currency's minor unit. Omit for a full refund. For a partial refund send the running total, not the amount of this one refund. Required when `refundStatus` is `canceled`: send the total that stays refunded after the cancellation (`0` when none remain)."
  2. Changed4 schema fields changedv0.19.33
    • addedInput schema / properties / amendmentType / description
      Added value: +"Defaults to `REFUND`, which covers full refunds, partial refunds, and refund cancellations. `CHARGEBACK` is always a full reversal."
    • addedInput schema / properties / amountRefunded / description
      Added value: +"Total refunded so far, in the currency's minor unit. Omit for a full refund. For a partial refund send the running total, not the amount of this one refund."
    • changedInput schema / properties / campaignId / description
      Previous value: -"Target program (campaign) id for this call. Defaults to GROWSURF_CAMPAIGN_ID when omitted. Program IDs also identify newly created programs without restarting the server."New value: +"Target program id for this call: the `id` returned by `growsurf_list_campaigns`, not the program name or a share URL. Defaults to GROWSURF_CAMPAIGN_ID when omitted. Program IDs also identify newly created programs without restarting the server."
    • addedInput schema / properties / refundStatus / description
      Added value: +"Refund status. Send `canceled` with the original `refundId` to cancel that refund."
  3. Changed15 schema fields changedv0.19.27
    • addedInput schema / properties / amount / minimum
      Added value: +1
    • addedInput schema / properties / amountRefunded / minimum
      Added value: +0
    • addedInput schema / properties / chargeId / maxLength
      Added value: +500
    • addedInput schema / properties / currency / maxLength
      Added value: +3
    • addedInput schema / properties / currency / minLength
      Added value: +3
    • addedInput schema / properties / currency / pattern
      Added value: +"^[A-Za-z]{3}$"
    • addedInput schema / properties / description / maxLength
      Added value: +500
    • addedInput schema / properties / externalId / maxLength
      Added value: +500
    • addedInput schema / properties / invoiceId / maxLength
      Added value: +500
    • addedInput schema / properties / orderId / maxLength
      Added value: +500
    • addedInput schema / properties / paymentId / maxLength
      Added value: +500
    • addedInput schema / properties / paymentIntentId / maxLength
      Added value: +500
    • addedInput schema / properties / refundId / maxLength
      Added value: +500
    • addedInput schema / properties / refundStatus / maxLength
      Added value: +500
    • addedInput schema / properties / transactionId / maxLength
      Added value: +500
  4. Changed2 schema fields changedv0.19.15
    • addedInput schema / properties / campaignId / minLength
      Added value: +1
    • addedInput schema / required
      Added value: +[
      +  "campaignId"
      +]
  5. Changed1 schema field changedv0.19.9
    • changedInput schema / properties / campaignId / description
      Previous value: -"Target program (campaign) id for this call. Defaults to GROWSURF_CAMPAIGN_ID when omitted. Pass the `id` returned by growsurf_create_campaign to configure or operate a program you just created, without restarting the server."New value: +"Target program (campaign) id for this call. Defaults to GROWSURF_CAMPAIGN_ID when omitted. Program IDs also identify newly created programs without restarting the server."
  6. Changed6 schema fields changedv0.14.0
    • changedInput schema / allOf
      Previous value: -[
      -  {
      -    "anyOf": [
      -      {
      -        "required": [
      -          "participantId"
      -        ]
      -      },
      -      {
      -        "required": [
      -          "participantEmail"
      -        ]
      -      }
      -    ]
      -  },
      -  {
      -    "anyOf": [
      -      {
      -        "required": [
      -          "externalId"
      -        ]
      -      },
      -      {
      -        "required": [
      -          "transactionId"
      -        ]
      -      },
      -      {
      -        "required": [
      -          "orderId"
      -        ]
      -      },
      -      {
      -        "required": [
      -          "paymentId"
      -        ]
      -      },
      -      {
      -        "required": [
      -          "invoiceId"
      -        ]
      -      },
      -      {
      -        "required": [
      -          "paymentIntentId"
      -        ]
      -      },
      -      {
      -        "required": [
      -          "chargeId"
      -        ]
      -      }
      -    ]
      -  }
      -]New value: +[
      +  {
      +    "anyOf": [
      +      {
      +        "required": [
      +          "participantId"
      +        ]
      +      },
      +      {
      +        "required": [
      +          "participantEmail"
      +        ]
      +      }
      +    ]
      +  },
      +  {
      +    "anyOf": [
      +      {
      +        "required": [
      +          "externalId"
      +        ]
      +      },
      +      {
      +        "required": [
      +          "transactionId"
      +        ]
      +      },
      +      {
      +        "required": [
      +          "orderId"
      +        ]
      +      },
      +      {
      +        "required": [
      +          "paymentId"
      +        ]
      +      },
      +      {
      +        "required": [
      +          "invoiceId"
      +        ]
      +      },
      +      {
      +        "required": [
      +          "paymentIntentId"
      +        ]
      +      },
      +      {
      +        "required": [
      +          "chargeId"
      +        ]
      +      }
      +    ]
      +  },
      +  {
      +    "if": {
      +      "required": [
      +        "paymentProvider"
      +      ]
      +    },
      +    "then": {
      +      "required": [
      +        "testMode",
      +        "transactionId"
      +      ]
      +    }
      +  },
      +  {
      +    "if": {
      +      "not": {
      +        "required": [
      +          "paymentProvider"
      +        ]
      +      }
      +    },
      +    "then": {
      +      "not": {
      +        "required": [
      +          "testMode"
      +        ]
      +      }
      +    }
      +  }
      +]
    • addedInput schema / properties / paymentProvider
      Added value: +{
      +  "description": "Connected provider for the original payment. Requires its `transactionId` and `testMode`. This amends GrowSurf records without sending a refund through the provider.",
      +  "enum": [
      +    "stripe",
      +    "chargebee",
      +    "recurly"
      +  ],
      +  "type": "string"
      +}
    • addedInput schema / properties / refundAmount / description
      Added value: +"Positive amount for this individual refund, no greater than the sale amount, in the sale currency's minor unit. Send it with `refundId` on each original refund to support cancellations and out-of-order amendments. The amount for a given `refundId` cannot change. A cancellation can omit it when the original amount is already recorded. Incomplete refund history returns `409` without applying the cancellation. Newly observed higher cumulative refunds and incomplete coverage are retained for reconciliation."
    • addedInput schema / properties / refundHistoryComplete
      Added value: +{
      +  "description": "Set true only after reconciling and recording every original refundId and refundAmount, including refunds later canceled. This confirmation resolves previously incomplete history. Omit during ordinary delivery. Replaying an old confirmation cannot resolve a later gap; confirm a newly reconciled refund or complete provider list.",
      +  "type": "boolean"
      +}
    • addedInput schema / properties / refundId / description
      Added value: +"Stable per-refund identifier. Required when canceling a refund or changing the refunded total after a cancellation. Reuse the original refund's identifier for its cancellation. An amendment without enough refund identity returns `409` without applying the cancellation. Newly observed higher cumulative refunds and incomplete coverage are retained for reconciliation."
    • addedInput schema / properties / testMode
      Added value: +{
      +  "description": "Original payment mode: `true` for test or `false` for live. Requires `paymentProvider`.",
      +  "type": "boolean"
      +}
  7. First observedv0.12.2

TDQS

A4.1/5.0
Behavior5/5

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

Annotations already declare destructive=true, idempotent=true, and openWorld=true, but the description adds material behavior the agent could not infer: no funds move through the payment provider, already-paid commissions are not clawed back and are recorded for tax purposes only, and omitting `amountRefunded` implies a full refund. These are exactly the consequences an agent needs before invoking a destructive mutation.

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?

Five dense sentences, front-loaded with the action and scope, followed by constraints and side effects. Slight redundancy exists, since 'omitted `amountRefunded` means a full refund' restates the schema's own parameter description, but nothing is padding.

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

Completeness4/5

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

For a destructive, 21-parameter mutation this covers action, side effects, and key defaults, and an output schema exists so return values need no explanation. The main remaining gap is the relationship between the three refund-amount fields, which the description leaves to be inferred.

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

Parameters3/5

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

Schema description coverage is only 43% across 21 parameters, so the description carries real burden. It clarifies the identifier requirement (same one as the original sale), the `amountRefunded` omission default, and the `campaignId` versus `GROWSURF_CAMPAIGN_ID` fallback, but it never disambiguates `amount`, `refundAmount`, and `amountRefunded`, which is the most likely source of caller error, and most remaining params are left to the schema.

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

Purpose4/5

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

The description opens with a specific verb+resource: record a refund, partial refund, or chargeback against a previously recorded affiliate transaction, and it states that commission is reversed or adjusted. The phrase 'previously recorded' implicitly separates it from the sale-recording sibling, but no sibling is named explicitly, so differentiation is semantic rather than explicit.

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

Usage Guidelines4/5

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

It gives clear context for when to reach for this tool (amending an existing affiliate transaction) and an important exclusion: it does not send money through the payment provider, it only records the amendment. It also flags that the same transaction identifier as the original sale is required. What is missing is a named alternative for cases the agent should not use this tool for.

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

Deploy Server

Other Tools