Payout Split Management

Payout Split Management

Overview

A marketplace or multi-seller platform must split every payment between the platform (commission) and one or more sellers (net payout), withhold taxes where required, manage rolling reserves for refund protection, and disburse funds on a schedule. Stripe Connect is the industry standard for handling this — it legally routes funds to connected seller accounts, handles tax withholding and 1099 reporting, and eliminates the compliance risk of holding seller funds in a pooled bank account.

For Shopify, WooCommerce, and BigCommerce stores that operate as multi-vendor marketplaces, dedicated marketplace apps (like Dokan for WooCommerce) handle the payout split logic on top of Stripe Connect.

When to Use This Skill

• When building a marketplace with independent sellers who need earnings disbursements
• When your platform charges a percentage or flat commission on transactions
• When you need to comply with IRS 1099-K reporting requirements for sellers
• When managing rolling reserves for high-risk or new sellers
• When sellers are requesting faster payouts (daily/weekly vs. monthly)

Core Instructions

Step 1: Choose the right marketplace and payout architecture

Step 2: Set up Stripe Connect for seller payouts

Stripe Connect is required for any architecture where you want to route funds to sellers automatically (rather than collecting everything in your account and manually wiring sellers).

Choose the right Connect account type:

• Express accounts: Sellers onboard via a Stripe-hosted form; Stripe handles identity verification (KYC); best for most marketplaces
• Custom accounts: You control the onboarding UX entirely; more complex; for platforms with specific UX requirements
• Standard accounts: Sellers connect an existing Stripe account; they see your platform in their Stripe dashboard

For most marketplaces, Express accounts are the right choice.

Set up Stripe Connect in the Stripe Dashboard: 1. Go to Stripe Dashboard → Connect → Overview and configure your platform 2. Enable Express accounts under Connect → Settings → Account types 3. Configure your platform's branding (name, logo, colors) for the hosted onboarding flow 4. Set the commission structure in your platform settings (not Stripe — Stripe routes funds based on the amounts you specify per transaction)

---

WooCommerce (Dokan)

1. Install Dokan Multivendor Marketplace (free base + paid extensions from dokan.wedevs.com) 2. Go to Dokan → Settings → Selling Options and configure:

• Commission type: percentage (e.g., 15% of each sale goes to the platform), flat fee, or combined
• Commission rate: the percentage or flat amount you keep as the marketplace

3. Go to Dokan → Settings → Withdrawal and configure payout schedules (weekly, bi-weekly, monthly) and minimum withdrawal amount 4. Enable Stripe Connect: go to Dokan → Settings → Payment → Stripe Connect and enter your Stripe Connect platform keys 5. Sellers connect their Stripe accounts by going to their vendor dashboard and clicking Payment Settings → Connect with Stripe 6. When an order is placed, Dokan automatically splits the payment: the seller's share is transferred to their connected Stripe account, the commission stays in your platform's Stripe balance

1099 reporting with Dokan: Dokan tracks cumulative payouts per seller. Export vendor earnings reports from Dokan → Reports → Vendor Wise Sales for 1099 preparation. For automatic 1099 generation, use TaxBandits or Track1099 — import the Dokan export and generate IRS-compliant 1099-K forms.

Shopify (Multi-Vendor Marketplace app)

1. Install Multi-Vendor Marketplace or Marketplace Kit from the Shopify App Store (various providers) 2. Configure vendor commission rates in the app's vendor settings 3. Connect Stripe Connect for payouts in the app's payment settings 4. Vendors are onboarded via a hosted form and can view their earnings and request payouts from a vendor portal

BigCommerce

1. Install a multi-seller marketplace app from the BigCommerce App Marketplace 2. Configure commission rates and payout schedules in the app settings 3. Connect Stripe Connect for automatic fund routing

---

Custom / Headless

For custom marketplace builds, implement the full split payout architecture using Stripe Connect:

Seller onboarding (Express accounts):

// Create an Express Connect account for a new seller
const account = await stripe.accounts.create({
  type: 'express',
  country: 'US',
  email: sellerEmail,
  capabilities: { transfers: { requested: true } },
  metadata: { seller_id: sellerId },
});

// Generate onboarding link — redirect seller to complete Stripe's KYC form
const accountLink = await stripe.accountLinks.create({
  account: account.id,
  refresh_url: `${process.env.PLATFORM_URL}/sellers/onboarding/retry`,
  return_url: `${process.env.PLATFORM_URL}/sellers/onboarding/complete`,
  type: 'account_onboarding',
});

// Save account.id to your database and redirect seller to accountLink.url
await db.sellers.update({ where: { id: sellerId }, data: { stripeAccountId: account.id } });

Splitting payment at checkout (Destination charge pattern):

// Create a payment intent that automatically routes commission to your platform
// and the seller's share to their connected account
const paymentIntent = await stripe.paymentIntents.create({
  amount: orderTotalCents,
  currency: 'usd',
  payment_method_types: ['card'],
  application_fee_amount: Math.round(orderTotalCents * commissionRate), // Platform commission
  transfer_data: {
    destination: seller.stripeAccountId, // Seller's Connect account
  },
  metadata: { order_id: orderId, seller_id: sellerId },
});

Rolling reserve (withhold a % for refund protection):

// Instead of immediate transfer, create a manual transfer on a delay
const transfer = await stripe.transfers.create({
  amount: Math.round(sellerNetEarningsCents * (1 - ROLLING_RESERVE_RATE)), // 95% transferred now
  currency: 'usd',
  destination: seller.stripeAccountId,
  transfer_group: `order_${orderId}`,
  metadata: { order_id: orderId, reserve_amount: Math.round(sellerNetEarningsCents * ROLLING_RESERVE_RATE) },
});

// Schedule the reserve release 90 days later via a cron job or job queue
await reserveQueue.add('release-reserve', {
  sellerId: seller.id,
  orderId,
  reserveAmount: Math.round(sellerNetEarningsCents * ROLLING_RESERVE_RATE),
}, { delay: 90 * 24 * 60 * 60 * 1000 });

1099-K tracking:

Track each seller's gross transaction volume in real-time. For 2024+, the IRS 1099-K threshold is $600.

// Update seller YTD earnings after each order
await db.sellers.update({
  where: { id: sellerId },
  data: { ytdGrossVolume: { increment: orderSubtotal }, ytdTransactions: { increment: 1 } },
});

// Alert when approaching $600 threshold — request W-9 before first payout
const seller = await db.sellers.findUnique({ where: { id: sellerId } });
if (seller.ytdGrossVolume >= 400 && !seller.w9Collected) {
  await sendW9RequestEmail(seller);
}

For 1099 form generation, use TaxBandits API or Track1099 API rather than building IRS form generation from scratch.

Step 3: Configure payout schedules and seller portal

Stripe Connect payout schedule: In the Stripe Dashboard under Connect → Settings → Payouts, configure the default payout schedule for connected accounts (daily, weekly, or monthly). Individual seller accounts can request changes to their schedule within your platform's settings.

Seller earnings dashboard: Sellers need visibility into their earnings, pending payouts, and reserves. Build or use a pre-built portal:

• Dokan/WCFM: includes a vendor dashboard with earnings, payout requests, and payment history
• Custom: use the Stripe Connect Account Balance API to show sellers their available balance in real-time

Best Practices

• Use Stripe Connect Express or Custom accounts — never hold seller funds in a pooled bank account; use Stripe Connect to ensure funds are legally owned by the platform until transferred
• Collect W-9 before first payout — without a W-9, you must apply 24% IRS backup withholding; make W-9 collection part of seller onboarding
• Calculate earnings at order capture, not payout time — earnings records should be immutable and linked to specific orders; the payout is a separate aggregation step
• Implement rolling reserves for new sellers — withhold 5–10% for 90 days to protect against refunds and chargebacks; release automatically on schedule
• Store commission rates as snapshots — commission rates change over time; never recompute historical earnings with the current rate; record the rate at the time of each sale

Common Pitfalls

Related Skills

• @stripe-integration
• @payment-reconciliation-automation
• @accounts-receivable-automation
• @tax-compliance-automation
• @invoice-generation-automation

Year-End Tax Reporting and Reserve Management

Problem/Feature Description

ArtisanHub is a marketplace for independent craftspeople that has been running for two years. As January approaches, their finance team has two urgent problems. First, they need to file 1099 forms for qualifying sellers — but no one on the team is sure exactly who qualifies under the rules that changed recently, whether the form should report gross sales or just what the seller was paid after fees, and how to handle sellers who never submitted their tax paperwork. Second, the rolling reserve funds held back from early sellers are maturing and need to be released automatically — the current manual process is error-prone and sellers are complaining about delayed access to their money.

The engineering team needs: (1) a JavaScript service that generates 1099 records for the correct set of sellers using the current IRS threshold, and (2) a daily job that finds and releases matured reserve funds. The finance team also wants a monitoring query they can run to quickly see which active sellers are approaching the filing threshold and whether their W-9 status creates any compliance risk.

Output Specification

Produce the following files:

• tax-reporting.js — the 1099 generation service
• reserve-release-job.js — the daily reserve release job
• tax-compliance-notes.md — explains the threshold used, what amount is reported on the 1099, how W-9 status affects withholding, and the recommended W-9 collection trigger point
• seller-1099-status.sql — a SQL query that shows active sellers with their YTD earnings and a status column indicating whether they require a 1099, still need a W-9, or are below threshold

Marketplace Earnings Calculator

Problem/Feature Description

Craft & Co is a handmade goods marketplace launching next quarter. Their product team has finalized the business model: the platform takes a commission on every sale, Stripe handles card processing, and new sellers are placed on a reserve program for their first 90 days to protect against chargebacks. Some sellers — particularly those who signed up without completing their tax paperwork — will have income tax withheld directly from their earnings.

The engineering team needs a JavaScript module that calculates the exact amount a seller earns for a given order, breaking down every deduction so that earnings records are transparent and auditable. The module must handle multiple commission structures (the marketplace offers different rates to different seller tiers) and must produce a database record for every order — calculation happens at the moment the order is placed, not at payout time. Seller year-to-date totals must also be updated as part of this process, because the finance team uses them for end-of-year tax reporting.

Output Specification

Produce a file earnings-calculator.js containing the earnings calculation logic as a JavaScript module. The file should be self-contained and include inline comments explaining any non-obvious numeric constants or business rules. Also produce a calculation-notes.md that documents the calculation formula used, what each deduction represents, and any edge cases handled. The calculation-notes document should be detailed enough for a finance auditor to verify the logic.

Seller Disbursement Processor

Problem/Feature Description

GigMarket is a freelance services marketplace that has grown to 800 active sellers. Every week their finance team manually exports a spreadsheet of sellers owed money and wires funds one by one — a process that takes two days and has caused several payment errors. The CTO wants a fully automated batch disbursement system that runs on a schedule and reliably transfers the correct net amounts to each seller's bank account.

Sellers have already completed Stripe Connect onboarding as part of signup. Not all accounts are fully activated yet — some are still restricted or pending review — so the system needs to skip ineligible sellers gracefully rather than failing the entire batch. When a transfer succeeds, all the underlying earnings records need to be marked as disbursed in the same atomic operation so the books never fall out of sync with what Stripe actually paid out. When a transfer fails, the failure must be recorded with the reason so the finance team can investigate. The system should also handle the edge case where a seller's net amount is zero or negative after deductions, and instead of triggering a clawback, carry that balance forward.

Output Specification

Produce a file disbursement-processor.js implementing the batch disbursement logic as a JavaScript module. Include a disbursement-design.md document that describes the data flow, idempotency strategy, and how the system handles failure cases — detailed enough for a code reviewer to evaluate the correctness of the approach. Clean up any test artifacts before finishing.