Skip to main content
A payout is a settlement with one seller, in one currency. It gathers the earnings that seller has accrued and not yet been paid for, states the total, and names exactly which earnings it covers. A payout is a record of a settlement rather than the settlement itself. Where your marketplace is set to Your own books, creating a payout moves no money: you send the payment through your bank and then mark the payout as paid. Where a payment provider such as Stripe Connect is connected, the provider sends the money and the record follows it. Payouts are the second half of the seller ledger. The first half is seller transfers, which credit a seller as each of their orders is fulfilled. A payout gathers those credits and settles them. See Seller Transfers. To review payouts, navigate to Sellers → Payouts in the admin dashboard.

Reviewing Your Payouts

The Payouts list, with one pending payout The list shows one row per payout. Filters narrow the list by date, seller and status. The search box matches on the reference rather than on seller names.

Payout Statuses

What a status means depends on the Paid through setting under Marketplace Settings. Where that is set to Your own books, a payout is created as Pending and stays there until you mark it as paid, at which point it becomes Completed. No other status occurs, because nothing is being attempted on your behalf. Where a payment provider is connected, the provider moves the money and reports back, and a payout can also reach the following:

How Payouts Are Created

Payouts are created by a sweep that runs once a day and looks at every approved seller in turn. A seller is settled when both of the following hold. Their schedule is due. The schedule is set under Marketplace Settings as daily, weekly, every two weeks, monthly, or only when you say so. A seller carrying their own Payout schedule on their seller page follows that instead. Being due is measured from the seller’s last payout in that currency, so a seller who has never been paid in a currency is settled as soon as they are owed anything rather than waiting out a full period. A seller whose schedule is set to manual is never settled by the sweep. They are owed at least the minimum. The Minimum payout is also set under Marketplace Settings, with a seller’s own figure taking precedence. A balance below it is carried into the next period rather than being sent. One payout is created per currency. Nothing is converted, so a seller owed in two currencies receives two payouts rather than one combined figure. A payout gathers the seller’s unsettled transfers oldest first, and every refund is included whatever else is. A payout can therefore cover a sale, a refund and a second sale, which is why its total can be lower than the sales inside it. The period shown on the payout runs from the oldest earning it covers to the moment it was created.
Where a balance has gone negative, because refunds came to more than earnings, nothing is created and the shortfall is carried forward to be absorbed by what the seller earns next.

How to Settle a Seller Immediately

A seller's Balance card, showing what is owed Settle now gathers everything a seller is owed into a payout at once, without waiting for their schedule. This is how a seller on a manual schedule is paid by default.
  1. Navigate to Sellers and open the seller.
  2. On the Balance card, click Settle now.
  3. Read the confirmation and click Settle now again.
One payout is created per currency, exactly as the sweep creates them. No money moves, and each payout waits to be marked as paid.
The Balance card reads the same after settling. The amount stays under Owed, because owed counts what has been earned and not yet paid, and a payout that has not been marked as paid has not paid anything yet.

Reading a Payout

A payout, with the earnings it covers Opening a payout from the list shows the amount, the status and the seller in the header, over the two cards below. Covers N earnings lists every transfer in the payout, with the date, the order it came from, whether it was a sale or a refund, and the amount. This is what a seller needs to reconcile a deposit against their own records. Payout carries the settlement itself:
  • Amount - What the payout comes to.
  • Reference - The reference recorded when it was marked as paid, or Not provided where none was given.
  • Provider - What settled it. A marketplace keeping its own books reads Spree::PayoutProvider::System here.
  • Period - From the oldest earning in the payout to the moment the payout was created.

How to Mark a Payout as Paid

Marking a payout as paid records that the money reached the seller. It is what clears the amount from the seller’s balance, moving it from Owed to Paid out, so it is done after the payment has been sent rather than before. This is the step a marketplace paying through Your own books works through on payout day. Where a payment provider is connected, the provider confirms its own settlements and this is needed only in the one case described under Payouts Through Stripe Connect. The row menu on the payouts list, with Mark as paid It can be done from either of two places. On the payouts list, open the menu at the end of a row and click Mark as paid. On a payout’s own page, click Mark as paid in the header. Both open the same dialog. The Mark as paid dialog, with its reference field
  1. Send the payment to the seller through your bank.
  2. Open the payout, or the menu at the end of its row on the payouts list.
  3. Click Mark as paid.
  4. Enter the Reference the payment went out under, such as the bank reference, so it can be traced later. This is optional, and no two payouts can share one.
  5. Click Mark as paid in the dialog.
The payout becomes Completed and the reference is shown against it. The seller’s balance moves the amount from Owed to Paid out, and the seller sees the same change in their own panel.
Marking a payout as paid moves no money. It records a payment you made separately, so doing it before sending the money leaves the seller reading that they have been paid when they have not.
The action is offered on a payout that is Pending, Processing or Needs checking. A payout that is already Completed cannot be marked again, and a Failed one has already released its earnings to the next settlement.

Payouts Through Stripe Connect

Where Paid through is set to Stripe Connect, the records on this page are written in the same way and the same schedule governs them. What changes is that the money moves on its own, and payouts are completed by Stripe rather than by you. Setting the provider up is covered in Stripe Connect for Marketplaces.

How the Money Reaches a Seller

The money makes two separate moves rather than one.
  • As each order is fulfilled, the seller’s earning is transferred from your Stripe account to that seller’s connected account. The transfer is funded by the customer’s own charge, so it settles when that charge settles and your marketplace does not have to front the money. This is the seller transfer described under Seller Transfers.
  • When a payout is created, Spree instructs that connected account to pay its balance out to the seller’s bank. This is the payout.
Connected accounts are set up so that Stripe runs no payout schedule of its own. The Settle sellers interval under Marketplace Settings is therefore the only schedule in effect, exactly as it is without a provider.

Payouts Complete on Their Own

A payout created against Stripe Connect holds Stripe’s own payout identifier as its Reference from the moment it is created, and stays Pending until Stripe reports what happened to it.
  • When the money reaches the seller’s bank, the payout becomes Completed and the seller’s balance moves from Owed to Paid out. Nobody marks it.
  • When Stripe cannot send it, the payout becomes Failed and the earnings it held are released, so the next settlement picks them up and sends them again.
A bank can return a payout days after paying it, so a payout that has already completed can still be reported as failed later. The earnings are released in that case too, which keeps a seller’s balance correct rather than reporting them settled while Stripe still holds the money.
These confirmations arrive on a second Stripe webhook endpoint, separate from the one carrying your customers’ payments. Spree registers it when the Stripe payment method is saved. See Stripe Connect for Marketplaces.

When You Still Mark a Payout as Paid

One case remains. Where Stripe’s answer to a request was lost rather than refused, the payout is left at Needs checking, because nobody can tell whether the money moved and sending it again would risk paying twice. Check that payout against your Stripe dashboard. Where the money went out, mark it as paid with the Stripe payout identifier as the reference, which completes it in the same way the confirmation would have.

What a Seller Needs First

A seller is only credited once they hold a connected Stripe account, which they set up themselves from the Payout account row on their onboarding checklist. Until then their earnings are recorded and held at Pending, and are sent once their account can receive them. See Onboarding.

Why a Payout Can Be Smaller Than the Balance

A seller’s earning is credited when their order is fulfilled, but the money behind it only reaches their connected account once the customer’s charge settles with Stripe. Those are not the same moment. Before creating a payout, Spree asks Stripe what the seller’s account can actually send, and settles only that much, taking the oldest earnings first. Anything left over stays owed and goes out in the next settlement. Where Stripe cannot be reached for that figure, no payout is created for that seller in that period, and the balance carries forward intact.

Refunds

A refund writes its reversal against the seller’s ledger in the usual way, so balances and payouts stay correct from then on. The Stripe transfer behind the original earning is not pulled back, and a balance driven negative by refunds is absorbed by what the seller earns next rather than being recovered from them directly.

Further Reading