returns-and-refunds
Skill1 starsChanged 18 days agoMITView on GitHub
Run returns as a tracked RMA from request to inspection, refund only what the policy and payment allow, and restock only inspected items. Use when building a returns portal, refund rules, exchanges, store credit, or restocking after a return.
In this repository28 other files it gives its agents.
- b2b-pricingSkill
- catalog-import-and-migrationSkill
- checkout-ux-and-conversionSkill
- conversion-event-trackingSkill
- ecommerce-seo-structured-dataSkill
- fraud-and-risk-basicsSkill
- google-merchant-product-feedsSkill
- headless-nextjs-storefrontSkill
- inventory-and-multi-warehouseSkill
- iranian-payment-gatewaysSkill
- marketplace-search-and-rankingSkill
- mcp-store-toolingSkill
- multi-vendor-payoutsSkill
- order-and-webhook-reliabilitySkill
- payment-gateway-integrationSkill
- product-catalog-modelingSkill
- product-description-guardrailsSkill
- rtl-and-persian-localizationSkill
- shopify-app-developmentSkill
- storefront-accessibilitySkill
- storefront-performanceSkill
- stripe-paymentsSkill
- subscription-billingSkill
- tax-and-shippingSkill
- vector-product-searchSkill
- woocommerce-plugin-developmentSkill
- woocommerce-rest-apiSkill
- wordpress-plugin-securitySkill
The file
We split this skill into the rules it gives an agent
3 rules. About 0 are common, 3 are distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈3
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 16
Create a return record (an RMA) with the order, the lines and quantities, the reason, and the requested outcome: refund, exchange, or store …
- Distinctive: line 17
Check eligibility on the server: the return window from the delivery date, the product's returnable flag, quantities not already returned, …
- Distinctive: line 19
When the parcel arrives, inspect each line and record the condition: resellable, damaged, or missing.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Returns and refunds
A return is a small workflow with its own record, not a status on the order. Keep the return, the refund, and the stock movement separate, and link them. Statuses and the refund calculation are in the RMA notes.
Procedure
- Create a return record (an RMA) with the order, the lines and quantities, the reason, and the requested outcome: refund, exchange, or store credit.
- Check eligibility on the server: the return window from the delivery date, the product's returnable flag, quantities not already returned, and final-sale items.
- Approve or reject with a reason. Approval issues return instructions or a label.
- When the parcel arrives, inspect each line and record the condition: resellable, damaged, or missing.
- Refund from the inspection result, not from the request. Use the refund calculation in the notes.
- Restock only resellable units, as a
returnstock movement. Damaged units go to a separate location or are written off. - Close the return. The order shows refunded amounts and return history but keeps its original lines.
Refunding
- Refund through the original payment method, using the gateway's refund API and an idempotency key per refund. Store the provider refund id.
- The total refunded on an order can never exceed what was captured. Check the sum of earlier refunds first.
- Refund tax in proportion to the refunded lines. Refund shipping only when the policy says so, such as for a wrong or damaged item.
- A partial refund leaves the order paid for the rest. Use the platform's refunded status only when everything is refunded.
- Store credit is a liability. Record it in a ledger with an expiry if the law allows one, not as a negative order.
- In WooCommerce, create refunds with
wc_create_refund()orPOST /wp-json/wc/v3/orders/{id}/refunds. Setapi_refundtotrueonly when the gateway should return the money; otherwise it is a manual refund record.
Exchanges
An exchange is a return plus a new order for the replacement, linked to the return. Reserve the replacement when the exchange is approved so it does not sell out while the parcel is in transit. Charge or refund the price difference on the new order.
Gotchas
- Restocking at approval puts units that never come back, or come back broken, on sale.
- Refunding at request time pays out for parcels that never arrive.
- A refund that is created only in the payment provider's dashboard leaves the shop showing the order as fully paid. Import provider refunds by webhook.
- Two staff members refunding the same line at once can exceed the captured amount. Lock the order or check the refund total inside the transaction.
- Some laws give a minimum withdrawal period for distance sales, such as 14 days in the EU. The store's window cannot be shorter for those customers.
Verification
- A return outside the window is refused with the reason shown.
- A line cannot be returned twice beyond its purchased quantity.
- A damaged unit is refunded per policy but not added to sellable stock.
- The sum of refunds never exceeds the captured amount, even with two concurrent requests.
- A partial refund leaves the order paid, with the refunded amount shown.
Evaluation
Worked examples and the checks they must satisfy are in evals/tasks.json.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

