chase-unpaid-commissions

name

chase-unpaid-commissions

description

Use this skill when a publisher wants to chase commissions that a network has validated (approved) but not yet paid, typically those sitting unpaid past a payment-term threshold such as 90 days. The skill pulls the matching transactions, groups them, and drafts a chase email with the unpaid sales attached. Trigger on: "chase my unpaid commissions", "which approved sales haven't been paid?", "draft a chase email for unpaid payments", "I've been validated but not paid in 90 days".

Operating instructions

You are helping a publisher chase commissions that have been validated (approved) but not paid and have aged past a payment-term threshold. The output is a per-network draft chase email with the relevant unpaid sales attached. You draft; the user sends. Never send anything yourself.

"Validated but not paid" means a transaction whose canonical status is approved and which has no datePaid. pending is not yet validated and is out of scope; reversed and paid are excluded.

Step 1 — identify the configured networks

Use publisher networks the user named or confirmed they configured. If none are known, ask which networks to include. Call affiliate_list_networks only to confirm that this server has a registered adapter for each named network; it does not prove that credentials are configured. When credential state is uncertain, recommend affiliate-networks-mcp doctor <slug> or attempt the requested operation and surface its verbatim error.

Only publisher-side networks (side === 'publisher') are in scope — chasing is a publisher action. Skip any side === 'advertiser' entries and say so. Inspect each publisher network's knownLimitations; where listTransactions is explicitly unsupported, report the coverage gap instead of calling it or claiming there is nothing to chase.

Step 2 — agree the threshold

Default threshold: 90 days unpaid. If the user named a different term (60 days, "past the payment terms", a calendar date), honour it. State the threshold you used in the output so the user can confirm it matches the network's actual payment terms.

The age that matters is days since validation, measured from dateApproved. If a transaction has no dateApproved, its ageDays field only proves days since conversion. Keep it in a separate "validation date unavailable" review list; do not claim it has exceeded the payment term or include it in a chase total until the user verifies the validation date.

Step 3 — optional pre-check

For each network slug s, call affiliate_<s>_get_earnings_summary({ from, to }) over a window wide enough to cover every transaction that could be past the threshold. Read oldestUnpaidAgeDays, remembering that it is measured from conversion and may include both pending and approved rows:

• If the summary is confirmed complete and oldestUnpaidAgeDays is absent or below the threshold, skip the transaction pull and note "nothing past threshold".
• If completeness is unclear or oldestUnpaidAgeDays meets or exceeds the threshold, proceed to step 4.

Do not treat a failed summary call as "nothing to chase". Surface the verbatim error and still attempt step 4.

Step 4 — pull the unpaid, validated transactions

For each in-scope network, call:

affiliate_<s>_list_transactions({ status: "approved", minAgeDays: <threshold>, from: <iso>, to: <iso> })

minAgeDays is a coarse filter computed against dateConverted, so it is a pre-filter, not the final answer. The tool returns a Transaction[]; upstream pagination is the adapter's responsibility. Do not expect a cursor in the response or silently assume a limited or truncated response is complete.

After the call, keep only the transactions where:

• status === "approved", and
• datePaid is absent, and
• dateApproved is present, and
• days between dateApproved and today >= the threshold.

Put approved, apparently unpaid rows with no dateApproved in the separate review list from step 2. If a call fails, surface the verbatim error (network, operation, message, httpStatus) and continue with the remaining networks; flag the gap at the top of the output. Never silently drop a network.

Step 5 — group and total

For each network, group the surviving transactions by programmeName. Within each programme, sum commission per currency — never apply FX. For each group record: transaction count, total commission per currency, and the oldest unpaid age in days.

If a network produced nothing past threshold, say so explicitly.

Step 6 — draft one chase email per network

Networks pay publishers, so the default recipient is the network's publisher / finance support, not the merchant. Draft one email per network. If a single programme dominates and the user wants to go direct to the merchant, draft a per-programme variant instead, but say which you chose and why.

Each draft has:

1. Subject — e.g. Unpaid validated commissions — <Network> — <publisher id/name>.

2. Recipient — leave a [network publisher support / finance contact] placeholder; you do not hold contact data. Include the network's docsUrl only when it is relevant; do not present it as a verified support channel.

3. Body — matter-of-fact, UK English, no chasing-language theatrics. State: the publisher account, the payment term being invoked, the number of transactions, the total per currency, and a request for a payment date or an explanation. Reference that the itemised sales are attached.

4. Sales table — inline in the body for readability:

   Transaction ID	Programme	Converted	Validated	Days unpaid	Commission

5. Attachment — write the same rows to a CSV the user can attach, named unpaid-commissions-<slug>-<YYYY-MM-DD>.csv, with a header row and one row per transaction (transaction_id,programme,date_converted,date_approved,days_unpaid,commission,currency). If you cannot write files in this environment, render the CSV in a fenced block so the user can copy it into a file.

   Escape CSV fields correctly. Because the file may be opened in a spreadsheet, neutralise any text field beginning with =, +, -, or @ so upstream programme names or ids cannot execute as formulas.

If an email tool is connected (for example a Gmail MCP with a draft action), you may create a draft with the body above and attach the CSV — but only a draft. Confirm with the user before creating it, and never send.

Step 7 — summarise for the user

Above the drafts, give a short ledger: per network, transactions chased and total per currency, plus rows needing validation-date review, networks skipped (nothing past threshold), and networks that failed (verbatim error). Then present the drafts and the attachment(s).

Large accounts

On accounts where a pull runs to tens of thousands of rows, keep every tool result within the client's size limit:

• Prefer summaries: affiliate_<slug>_get_earnings_summary answers totals and status splits without pulling transaction rows.
• When raw rows are needed, pull month-sized windows rather than the whole period in one call, and page with offset (using limit as the page size) when a window is still too big.
• If a result returns truncated: true or result_too_large, follow its hint: continue from the given nextOffset or narrow the window or filters. Never total a truncated pull as if it were complete.

Constraints

• Draft only. Sending a chase email is a write action with external consequences; it stays with the user.
• Never invent figures, dates, or transaction IDs. If a field is missing, leave it blank and note it — do not fill in zeros or guesses.
• Respect each transaction's currency. Sum per currency; never normalise or convert.
• Quote the verbatim upstream error on any failed call. Do not collapse a failure into "no unpaid commissions".
• The threshold is the user's payment term, not a universal rule. State it.
• Never describe a threshold as the network's contractual or standard payment term unless the user supplied or verified that term.