[GiselleNessi]

Adds a "Fees on refunded requests" section to the Refunds concept page stating that Relay does not keep the service fee and does not collect app fees on a refunded request, with a two-row table and a link to the app-fee verification guidance. Adds one sentence to the App Fees verification paragraph so an empty paidAppFees on a refunded request is explained where integrators look for it.

Linear: https://linear.app/relayprotocol/issue/INT2-941/document-fee-treatment-for-refunded-requests

Verified against production: 15 refunded requests with a quoted app fee all have paidAppFees empty on /requests/v2. The wording avoids restating fee rules from fees.mdx; it only states what happens to fees on a refund.

Also fixes two prose mentions of /execute/permit on the App Fees page; the route is /execute/permits (solver api/execute/post-permits/v1.ts, OpenAPI spec, and the cURL on the same page).

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated
unevenlabs	🟢 Ready	View Preview	Nov 6, 2026, 9:14 AM

💡 Tip: Enable Automations to automatically generate PRs for you.

[github-actions]

Claude finished @GiselleNessi's task in 39s —— View job

---

Code review: PR #544

The table on the Refunds page names a fee that doesn't exist in the docs' fee model. The paragraph above it also makes an unverified claim about Execution Cost. The two anchor links resolve (#verifying-fee-collection and #fees-on-refunded-requests), and the heading level and table format follow AGENTS.md §2.

Issues

1. "Relay service fee" is not a term the docs define — references/api/api_core_concepts/refunds.mdx:42
fees.mdx lists four components: Execution Cost, Swap Cost, Platform Fees (formerly Relay Fees) and App Fees. The only "service fee" it mentions is the deprecated fees.relayerService field (fees.mdx:162), which it defines as "the service fee paid to the relayer". A reader can't tell whether this row means Platform Fees or relayerService. Use the names from fees.mdx, probably "Platform Fees", and link to /references/api/api_core_concepts/fees. The PR only checked app fees in production (paidAppFees), so the Platform Fees row also needs confirming against the solver.
Fix this →

2. Execution Cost on a refund is not covered, but the text rules it out — refunds.mdx:38
"The refund gas cost and any origin swap … are the only reasons the refund can be less than your deposit." That sentence also says nothing else from Execution Cost is kept, including the $0.02 flat fee and, for gasless requests, the origin gas Relay already paid for the user (fees.mdx, Execution Cost). The table doesn't list Execution Cost, and the PR doesn't show this was checked. Either confirm the claim and add an Execution Cost row, or soften "only reasons". The original refund-amounts list was already worded "several factors", not as a closed list.

3. "should not" on one page, "never" on the other — refunds.mdx:45 vs features/app-fees.mdx:63
The Refunds page says app fees "should not accrue on a refunded request". The App Fees page says refunded requests "never accrue app fees". The production check (15/15 had an empty paidAppFees) supports the stronger wording. Pick one and use it on both pages. "Should not" can read as "if you see a fee here, something is wrong", which is a different message.

Nits

• refunds.mdx:45 repeats line 43: "App fees should not accrue" says what the table row "Not collected" already says. You could cut it to "On a refunded request, paidAppFees on /requests/v2 is empty or zero. See Verifying Fee Collection." Naming the endpoint also helps readers who arrive from the Refunds page.
• The table has two rows and a single, mostly constant column. Two sentences or bullets would read just as well, but this is a style choice and the table follows §2.7.
• app-fees.mdx:63 says "empty or zero", while the PR body says production returned empty. That's fine; just make sure "zero" really can happen and isn't there only for safety.

Summary

No blockers on rendering or links. Please fix #1 (fee name) and check #2 (Execution Cost on refunds) with whoever owns refund accounting before merging. #3 is a quick wording fix.

[greptile-apps]

Confidence Score: 5/5

[Low impact] The PR appears safe to merge, with non-blocking documentation fixes remaining.

Findings

1.  Fee checks use retiring endpoint ▶
2.  Withdrawal links miss their section ▶

Summary

Documents that refunded requests do not retain Platform Fees or collect app fees.

• Refunded requests now have clear fee outcomes.
• App-fee withdrawal instructions point to /execute/permits.
• The App Fees page uses clearer wording in its balance and contract examples.

_{Reviews (5) · Last reviewed commit: "Merge branch 'main' into giselle/int2-94..." · Reviewed by Greptile}

[github-actions]

Claude finished @GiselleNessi's task in 25s —— View job

---

Code review: PR #544 (after 6097aa7)

The new commit is correct. It changes /execute/permit to /execute/permits in features/app-fees.mdx:113 and :179. The new name matches the endpoint stub (references/api/execute-permits.mdx → openapi: post /execute/permits), the cURL example on line 183, and the endpoint fields in the sample responses (app-fees.mdx:163, step-execution.mdx, gasless-swaps.mdx). The old singular form no longer appears anywhere outside the generated changelog.

The previous review's points about refunds.mdx are still open. This push didn't change that file.

1. "Relay service fee" is not a defined fee name. references/api/api_core_concepts/refunds.mdx:43
fees.mdx defines Execution Cost, Swap Cost, Platform Fees and App Fees. The only "service fee" it mentions is the deprecated relayerService field (fees.mdx:162). Rename the row to "Platform Fees" and link /references/api/api_core_concepts/fees. The production check only covered paidAppFees, so this row also needs confirming with whoever owns refund accounting.
   Fix this →

2. "The only reasons" leaves Execution Cost unaccounted for. refunds.mdx:38
   The sentence implies that nothing from Execution Cost is kept. That would include the flat fee and the origin gas Relay paid on gasless requests. Confirm this and add an Execution Cost row, or soften the wording to match the existing "several factors" framing.

3. The two pages state different certainty. refunds.mdx:45 says app fees "should not accrue", while app-fees.mdx:63 says they "never accrue". The 15/15 production check supports "never", so use it on both pages. You could also cut line 45 down to "On a refunded request, paidAppFees on /requests/v2 is empty or zero. See Verifying Fee Collection." so it doesn't repeat the table.

Summary

6097aa7 is good to merge. Items 1 and 2 still need a fix or confirmation from the fee or refund owner before the refunds section merges. Item 3 is a one-word fix.

[github-actions]

Claude finished @GiselleNessi's task in 32s —— View job

---

Code review: PR #544 (after 2fe67f2)

The new commit fixes all three items from the last review:

• Fee name (Add Just-In-Time gas guide #1): the table now says Platform Fees, which matches the component name in fees.mdx:26.
• "Only reasons" (Add sdk method docs #2): the commit removes that sentence. The existing "several factors" list in refunds.mdx:29-32 stays open-ended, so the page no longer says nothing else is deducted.
• Wording (Improve integration docs #3): refunds.mdx no longer says "should not accrue". It now just states that paidAppFees is empty or zero, which matches "never accrue" in features/app-fees.mdx:63.

The /execute/permits fix from 6097aa7 is still correct. Both anchors (#fees-on-refunded-requests and #verifying-fee-collection) resolve. No changelog entry is needed, because this describes existing behavior rather than changing it (§4.4).

Still open

The Platform Fees row hasn't been checked. references/api/api_core_concepts/refunds.mdx:42
The production check in the PR body only covered paidAppFees (15 out of 15 were empty). Nothing in the PR shows that Platform Fees go back to the user on a refund. This isn't a wording problem. It's a factual claim about refund accounting, so please get a quick confirmation from whoever owns refunds in the solver before merging. If the claim turns out to be wrong, users will expect a bigger refund than they get.

Nits (optional)

• Execution Cost and Swap Cost: fees.mdx lists four fee components, and the table covers two of them. Readers may wonder about the other two, especially the flat part of Execution Cost and the origin gas Relay pays on gasless requests. If the refund owner can confirm how those are handled, a third row would answer that. If not, leave the table as it is; the gas-deduction bullet above already covers the refund transaction's own cost.
• Line 38 repeats the table. You could cut it, or cut the table and keep one sentence: "Relay does not keep Platform Fees or collect app fees on a refunded request." Either works under §2.7.
• "Empty or zero": production only showed empty values. Keep "or zero" only if the API can actually return 0 there.

Summary

The PR is ready to merge once the Platform Fees refund claim is confirmed. Everything else is optional.

[github-actions]

Claude finished @GiselleNessi's task in 33s —— View job

---

Code review: PR #544 (after 42a3a8e)

• Read the diff for the new commit and the full PR
• Check inbound links to changed headings
• Post review

The new commit renames a heading that a changelog entry links to, so that link no longer reaches its section. The other edits in the commit are good: "api" → "API", "owned by the contract owner", the cleaner USDC sentence, and dropping the stray _USDC,_ italics.

Issue

1. The renamed heading breaks an anchor link. features/app-fees.mdx:111
### How to withdraw your off-chain balance? → ### Withdraw your off-chain balance changes the anchor from #how-to-withdraw-your-off-chain-balance to #withdraw-your-off-chain-balance. The 2026-10-28 entry "App-fee claim recipient validated before debit" still links to the old anchor:

• references/api/changelog.mdx:18 (the source)
• changelog.mdx:27 (generated, reproduces the source verbatim)

With the old anchor, the link opens the top of the App Fees page instead of the withdrawal section. AGENTS.md §4.2 asks for inbound links to be updated in the same PR. Fix the anchor in references/api/changelog.mdx only. changelog.mdx is generated (§4.6), so don't edit it by hand; the next sync picks up the change.
Fix this →

Still open from the last review

2. Nobody has confirmed the Platform Fees row yet. references/api/api_core_concepts/refunds.mdx:38-42
"Relay does not keep Platform Fees … on a refunded request" is a claim about refund accounting. The production check in the PR body covered only paidAppFees. Please get a quick confirmation from the solver or refunds owner before merging.

Nits (optional)

• app-fees.mdx:8 now says "offchain", but lines 69, 81 and 111 still say "off-chain". AGENTS.md §5 spells "onchain" as one word, so "offchain" would be the consistent choice. If you change the heading on line 111, item 1's anchor changes again, so do both edits together.
• refunds.mdx:44: production only showed empty values. Keep "or zero" only if the API can actually return 0.

Summary

Fix the broken anchor (#1). Once someone confirms the Platform Fees claim (#2), the PR is ready to merge.

I couldn't run the code-review skill or diff against origin/main (shallow checkout, no merge base). This review is based on git diff HEAD~4 HEAD, which covers all four PR commits.

[greptile-apps]

Withdrawal links miss their section

Renaming this heading changes its link target to #withdraw-your-off-chain-balance, but changelog.mdx:27 and references/api/changelog.mdx:18 still link to #how-to-withdraw-your-off-chain-balance. Those links no longer jump to the withdrawal instructions. Keep the old heading anchor or update both links.

Suggested change

	### Withdraw your off-chain balance
	### How to withdraw your off-chain balance?

[github-actions]

Claude finished @GiselleNessi's task in 31s —— View job

---

Code review: PR #544 (after 496bba3)

• Diff the PR against main
• Re-check open items from the previous review
• Post review

The new push is only a merge from main (496bba3). It brings in features/price-stabilization.mdx, style.css and changelog.mdx, and none of those overlap this PR's files. The PR content is the same as in 42a3a8e, so both items from the last review are still open.

Issues

1. Broken anchor from the renamed heading (not fixed yet). features/app-fees.mdx:111
The heading ### How to withdraw your off-chain balance? became ### Withdraw your off-chain balance, so its anchor is now #withdraw-your-off-chain-balance. Two places still link to the old anchor /features/app-fees#how-to-withdraw-your-off-chain-balance:

• references/api/changelog.mdx:18 is the source file, so fix the link there.
• changelog.mdx:53 is generated (AGENTS.md §4.6). Don't edit it by hand; the next sync will pick up the fix.

For now, that link opens the top of the App Fees page instead of the withdrawal steps. AGENTS.md §4.2 says inbound links should be updated in the same PR. Greptile flagged the same thing.
Fix this →

2. The Platform Fees claim still needs confirming. references/api/api_core_concepts/refunds.mdx:38-42
The page says "Relay does not keep Platform Fees … on a refunded request". Nothing backs that up yet:

• The production check in the PR body only looked at paidAppFees.
• fees.mdx doesn't mention refunds anywhere.

If the claim is wrong, users will expect a bigger refund than they actually get. Please get confirmation from whoever owns refunds in the solver before merging, or remove the Platform Fees row and keep only the app-fees statement, which production does support.

Rechecked and fine

• /execute/permits appears at app-fees.mdx:113 and :179, and no singular /execute/permit is left in prose.
• The links #fees-on-refunded-requests and #verifying-fee-collection both point to headings that exist.
• The wording edits ("API", "owned by the contract owner", removing the _USDC,_ italics) are correct.
• No changelog entry is needed, because this documents existing behavior (§4.4).

Nits (optional, carried over)

• "Empty or zero" (refunds.mdx:45, app-fees.mdx:63): production only returned empty values, so keep "or zero" only if the API can actually return 0.
• app-fees.mdx mixes "offchain" (line 8) with "off-chain" (lines 69, 81, 111). If you change the heading on line 111 to "offchain", update the anchor in item 1 to match.

Summary

Fix the anchor (#1), which is a one-line change, and confirm or drop the Platform Fees row (#2). After that, the PR is ready to merge.

[greptile-apps]

Fee checks use retiring endpoint

The new refund guidance sends readers to /requests/v2, which already has reduced rate limits and retires on November 24, 2026. Integrators following it will soon be unable to check their fees. Point to /requests/v3 and note its API-key requirement instead.

Suggested change

	On a refunded request, `paidAppFees` on `/requests/v2` is empty or zero. To check, see [Verifying Fee Collection](/features/app-fees#verifying-fee-collection).
	On a refunded request, `paidAppFees` on `/requests/v3` is empty or zero. Requests to `/requests/v3` require an `x-api-key` header. See [Migrating to Requests v3](/references/api/api_guides/migrating-to-requests-v3) for details.