multi-vendor-payouts
Skill1 starsChanged 18 days agoMITView on GitHub
Split a marketplace order by vendor, record commission as ledger entries, and pay vendors only settled amounts. Use when adding vendor catalogs, commissions, refunds that cross vendors, or payout batches.
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
- order-and-webhook-reliabilitySkill
- payment-gateway-integrationSkill
- product-catalog-modelingSkill
- product-description-guardrailsSkill
- returns-and-refundsSkill
- 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
5 rules. About 0 are common, 3 are distinctive, and 2 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.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 12
Use this skill when more than one vendor sells on one order.
- Distinctive: line 14
Do not name a vendor plugin's internal functions unless that plugin is in the project and you have read them.
- Very specific: line 18
Put vendor_id on every sellable line.
- Very specific: line 46
Call the payout provider with payout_{batchId}.
- Distinctive: line 53
If the payout already left, the reversal is a negative balance on the next batch, not a deleted history.
≈ “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
Multi-vendor payouts
Use this skill when more than one vendor sells on one order. Catalog shape is the product-catalog skill. Charging the shopper is the payment skill. This skill records who is owed what after that charge.
Do not name a vendor plugin's internal functions unless that plugin is in the project and you have read them. The ledger below is the model to implement, including when the store uses an existing multi-vendor extension.
Procedure
- Put
vendor_idon every sellable line. A line without a vendor cannot be paid out. - On payment, write ledger entries. Do not edit the line price to "take commission". Commission is its own entry.
- Decide, in data, who is merchant of record for the goods, the tax, and the shipping. Do not assume the vendor is.
- Hold entries until the refund window or the delivery rule you stored. A payout batch sums only entries that are payable.
- Send the payout with an idempotency key. A second run of the same batch does not pay twice.
- A refund writes reversing entries. It does not delete the original lines.
The entry types are in the ledger notes. Worked examples and checks are in evals/tasks.json.
Ledger entry
Each entry has: id, order_id, vendor_id or platform, type, amount in integer minor units, currency, available_at, and payout_id once paid.
Amounts are signed. A sale credit to the vendor is positive. Commission the platform keeps is negative on the vendor and positive on the platform, or two explicit entries that sum to the same result. Pick one representation and use it everywhere.
amount uses the order currency. Do not convert to a payout currency inside the entry. Conversion, if it exists, is a later payout step with its own rate and timestamp.
When money becomes payable
- Authorization is not a sale. Write no payable entry until the payment skill marks the order paid.
available_atis at least the refund window, or the delivery confirmation, whichever the marketplace rule uses.- Pending entries can be displayed as upcoming. They are excluded from the payout sum.
Payout batch
- Select entries where
available_atis in the past,payout_idis null, and the vendor account is allowed to receive funds. - Group by vendor and currency.
- Persist the batch and stamp
payout_idin the same transaction as the decision to pay. - Call the payout provider with
payout_{batchId}. If the call times out, retry with that key and do not create a second batch. - A provider failure clears nothing silently. The batch stays
processingor moves tofailedwith the entries still reserved, so a retry cannot select them into a new batch.
Refunds
- Refund the shopper through the payment skill for the amount they paid.
- Reverse the vendor net and the commission in proportion to the refunded lines, including tax if the vendor was credited for tax.
- If the payout already left, the reversal is a negative balance on the next batch, not a deleted history.
Gotchas
- One order can contain two vendors. A single commission percent on the order total assigns one vendor's shipping to the other.
- Paying the gross and also forgetting to retain commission overpays the vendor.
- Summing order totals again at payout time double-counts if the ledger is also summed.
- Blocking a vendor after entries are
processingmust not release those entries back into the selectable pool.
Verification
- A paid two-vendor order produces entries whose vendor nets plus platform commission equal the goods total you intended to split.
- An unpaid order produces no payable entries.
- Running the payout job twice creates one provider payout per vendor.
- A refund after payout reduces the next batch and leaves the original entries in place.
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.

