Skip to main content
Glama
GrowSurf MCP Server

GrowSurf MCP Server

Official

Record Sale

growsurf_record_sale
Idempotent

Record an affiliate-program sale with a unique transaction identifier to deduplicate repeat submissions and prevent double-paying the referrer; optionally target a campaign.

Instructions

Record a sale/transaction for an affiliate program. Use webhooks to know when commissions are added. Requires at least one transaction identifier (externalId, transactionId, orderId, paymentId, invoiceId, paymentIntentId, or chargeId) so repeated calls are de-duplicated instead of double-paying the referrer; reuse the same one when refunding. Targets campaignId if you pass it, otherwise GROWSURF_CAMPAIGN_ID.

Input Schema

NameRequiredDescriptionDefault
paidAtNoWhen the payment was captured or settled, as a Unix timestamp in milliseconds.
orderIdNo
chargeIdNo
currencyYes3-letter ISO 4217 currency code for the sale. A sale in another currency is converted to the program currency.
testModeNoRequired with `paymentProvider`: `true` for test or `false` for live. Otherwise omit.
invoiceIdNo
netAmountNo
paymentIdNo
taxAmountNo
amountPaidNo
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.
customerIdNo
externalIdNo
totalTaxesNo
descriptionNo
grossAmountYes
invoiceTotalNo
amountCashNetNo
participantIdNo
transactionIdNoTransaction identifier to store for this sale. Used to detect duplicate submissions.
subscriptionIdNo
totalTaxAmountNo
paymentIntentIdNo
paymentProviderNoConnected provider for this payment. Requires `transactionId` and `testMode`. Supply matching `grossAmount` and `currency`; other payment IDs and tax or net-amount overrides are not accepted. GrowSurf reads payment details from the provider and detects duplicate webhook/API/manual submissions.
totalTaxAmountsNo
participantEmailNo
invoiceTotalExcludingTaxNo
invoiceSubtotalExcludingTaxNo

Output Schema

NameRequiredDescriptionDefault
messageNoHuman-readable result message.
successNo`true` when the sale was recorded; `false` when it matched an existing transaction.
duplicateNo`true` when the sale matched an existing transaction.
firstSaleNoWhether this was the referred customer's first recorded sale.
duplicateFieldsNoIdentifier fields that matched an existing transaction.
commissionsCreatedNoCommissions created by this duplicate request.
matchingCommissionIdsNoCommission ids that matched the submitted identifiers.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changedv0.19.34
    • addedInput schema / properties / currency / description
      Added value: +"3-letter ISO 4217 currency code for the sale. A sale in another currency is converted to the program currency."
    • addedInput schema / properties / paidAt / description
      Added value: +"When the payment was captured or settled, as a Unix timestamp in milliseconds."
    • addedInput schema / properties / transactionId / description
      Added value: +"Transaction identifier to store for this sale. Used to detect duplicate submissions."
  2. Changed1 schema field changedv0.19.33
    • 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."
  3. Changed9 schema fields changedv0.19.27
    • addedInput schema / properties / chargeId / maxLength
      Added value: +500
    • addedInput schema / properties / customerId / 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 / subscriptionId / 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
    • changedInput schema / required
      Previous value: -[
      -  "currency",
      -  "grossAmount"
      -]New value: +[
      +  "currency",
      +  "grossAmount",
      +  "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. Changed3 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 this payment. Requires `transactionId` and `testMode`. Supply matching `grossAmount` and `currency`; other payment IDs and tax or net-amount overrides are not accepted. GrowSurf reads payment details from the provider and detects duplicate webhook/API/manual submissions.",
      +  "enum": [
      +    "stripe",
      +    "chargebee",
      +    "recurly"
      +  ],
      +  "type": "string"
      +}
    • addedInput schema / properties / testMode
      Added value: +{
      +  "description": "Required with `paymentProvider`: `true` for test or `false` for live. Otherwise omit.",
      +  "type": "boolean"
      +}
  7. First observedv0.12.2

TDQS

A3.6/5.0
Behavior3/5

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

Annotations already declare idempotentHint=true, destructiveHint=false, openWorldHint=true, so the safety profile is covered. The description usefully explains the idempotency *mechanism* (duplicate submissions are de-duplicated rather than double-paying the referrer) and the campaign fallback, but says nothing about error behavior, permissions, or what a partial/mismatched provider submission does. Modest value added on top of annotations.

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?

Three tight sentences, with the core operation first and the constraints following. The semicolon-heavy middle sentence packs several rules together but no clause is filler.

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

Completeness3/5

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

An output schema exists, so return values need not be explained, and the description covers identity, refund flow, and campaign targeting. For a 28-parameter mutation, though, gaps remain around the participant identifier requirement and the paymentProvider/testMode interplay, which the schema encodes structurally but does not explain semantically.

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?

With 28 parameters and only 21% schema description coverage, the description has to compensate, and it does so for the seven interchangeable transaction identifiers and the campaignId default. It is silent on the two required money fields (currency, grossAmount) and on the participantId vs participantEmail choice that the schema's anyOf enforces, so the compensation is partial.

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?

States a specific verb and resource ("Record a sale/transaction for an affiliate program") and immediately frames the de-duplication identity requirement, so an agent knows exactly what operation this is. It does not explicitly name sibling tools or say when a different endpoint would be preferable, which keeps it just under a 5.

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?

Gives concrete operating guidance: at least one transaction identifier is mandatory, the same identifier must be reused for refunds, and campaignId falls back to GROWSURF_CAMPAIGN_ID. It also routes the agent to webhooks for commission status instead of polling. There is no explicit when-not-to-use or named alternative tool.

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