agentleFS
sadrmaneshsadrmanesh/commerce-agent-skills/skills/multi-vendor-payouts/SKILL.md

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.

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
  1. Distinctive:

    Use this skill when more than one vendor sells on one order.

    line 12
  2. Distinctive:

    Do not name a vendor plugin's internal functions unless that plugin is in the project and you have read them.

    line 14
  3. Very specific:

    Put vendor_id on every sellable line.

    line 18
  4. Very specific:

    Call the payout provider with payout_{batchId}.

    line 46
  5. Distinctive:

    If the payout already left, the reversal is a negative balance on the next batch, not a deleted history.

    line 53

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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

  1. Put vendor_id on every sellable line. A line without a vendor cannot be paid out.
  2. On payment, write ledger entries. Do not edit the line price to "take commission". Commission is its own entry.
  3. Decide, in data, who is merchant of record for the goods, the tax, and the shipping. Do not assume the vendor is.
  4. Hold entries until the refund window or the delivery rule you stored. A payout batch sums only entries that are payable.
  5. Send the payout with an idempotency key. A second run of the same batch does not pay twice.
  6. 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_at is 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_at is in the past, payout_id is null, and the vendor account is allowed to receive funds.
  • Group by vendor and currency.
  • Persist the batch and stamp payout_id in 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 processing or moves to failed with 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 processing must 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.