Back to Blog
Guides

How to Tell Whether Your Shopify Payments Account Is on a Reserve

A reserve is Shopify Payments holding back part of what you have earned, against chargebacks or refunds that might come later. The comparison we published on this established two facts that make the question in the title harder than it sounds: the terms name no threshold that triggers one, and the decision is Shopify's to make at its own discretion. So this is the other half. Given that nobody will tell you the number, how does anyone actually know?

Four places, in a deliberate order. The first three are Shopify's own, and they outrank anything else. The fourth is any app that claims to know, ours included, and the test for the fourth is a single question: what does it do when it is not sure?

One: The Payouts Page, in Its Own Words

Start in your admin, on the Payouts page under Finances. That screen is the authority. If it tells you funds are being held, reserved, or withheld from a payout, that is the answer, and no app, no forum thread and no rule of thumb outranks it. If it tells you nothing of the kind, keep reading, because the absence of a notice is weaker evidence than the presence of one.

The reason to start here rather than with a tool is simple: everything a tool can see, it sees through the same account you are looking at. An app can organise the evidence. It cannot have more of it than you do.

Two: The Transaction List, Filtered to Three Types

Every Shopify Payments transaction carries a type, and three of the types are named for reserves. Through the API their names are RESERVED_FUNDS, RESERVED_FUNDS_REVERSAL and RESERVED_FUNDS_WITHDRAWAL; your admin shows the same movements in its own words alongside charges, refunds and payouts.

What the three types do and do not tell you

The first one is unambiguous: a RESERVED_FUNDS transaction is money moving into a reserve, and a run of them landing as orders come in is what a live percentage reserve looks like from the outside. The other two, Shopify's documentation names and does not explain. We are not going to explain them either. Any guide that tells you exactly what a reversal or a withdrawal means for your account is telling you more than the source does.

So the reading is this. Reserve-typed entries in your recent history mean a reserve has touched your account. The most recent one tells you the direction of the last movement. Whether the reserve is still open is a question the list answers only in combination with the page above it.

Three: The Terms' Own Description

The Shopify Payments terms describe a reserve account as funds held to cover chargebacks, refunds, disputes and other payment obligations, and they reserve to Shopify the right to set the terms of any such account. That is the whole description, and it is worth reading once, because it tells you what a reserve is for and that its size and duration are not something you can look up in advance. The comparison quotes the relevant passages, and the popular numbers you will find repeated elsewhere are addressed there too. This guide is not going to restate them.

Four: Any App, With One Question

Only now an app, and the question to ask of any of them is not what does it say but what does it do when it is not sure. A reserve is exactly the kind of fact a tool can be confidently wrong about, in either direction, and the direction it chooses to fail in tells you whether it was built to inform you or to alarm you.

Payout Guard is our app in this space, so it is the worked example, and the answers below are read from its source rather than from its marketing.

What it reads

The same transaction types listed above, from the same account you are looking at. The account object Shopify exposes has no reserve field, so there is nothing more direct to read. The app was already paging through those transactions to count charges for its chargeback rate; the reserve signal is the type column of the same rows.

When it claims a reserve, and when it declines to

It claims an active reserve only when the most recent reserve-typed event adds to the reserve and falls inside a window of thirty days, a constant in the source named RESERVE_WINDOW_DAYS. The reversal and withdrawal types are given no meaning at all. In the words of the comment beside the rule, the app only declines to claim a reserve when one of them is the latest word.

The window exists because a lapsed reserve does not always emit a closing event, while a live one keeps accruing as orders come in. And the comment states the direction of failure in three words: it fails toward not claiming. When the evidence is incomplete, the app says nothing rather than something.

Why it fails that way, in numbers you can check

When a reserve is active, the app's Payments pillar scores 15 out of 100, its critical band. The overall health score is round(0.6 * worst + 0.4 * mean) across four pillars, weakest-pillar-dominant by design. Put a 15 into that formula with the other three pillars perfect and it cannot get out of the low forties, well below the line where the app starts drafting an appeal outline for you.

So a false positive would brand a healthy store critical and hand its owner an appeal they do not need. That is the trade behind the window: the app would rather miss a one-time hold that lapsed quietly than do that to a healthy store. You may weigh it differently. The point is that the trade is written down and you can read it.

The same rule shows up one branch earlier. If the app cannot read your payments data on a run, the pillar reports itself as not checked. It does not report 100 and it does not report that you are not on Shopify Payments, because a failed read is no evidence of either. A tool that cannot say I could not look will eventually tell you a healthy account is fine on a day it never saw it.

Two Limits, Stated Plainly

Both are consequences of the choices above, and both go in this guide because a limit an app does not publish is a limit you will meet at the worst moment.

Where the reading can be wrong

The page-through is bounded. The app reads back through a fixed maximum number of transactions. A very high-volume store can have more than that inside the window, and the oldest part of the window is then simply not read.

An older one-time hold goes silent. A rolling percentage reserve keeps emitting reserve-typed transactions as orders land, so it stays visible. A reserve applied as a single hold on an older account emits its event once; after the thirty-day window closes, the app reads it as inactive whether or not Shopify has released it. This is the false-negative direction the window was chosen for, and it is where place one on this list, the Payouts page, is the one that knows.

The signal exists at all because of a gap we found and closed on the tenth of this month. The field for an active reserve had been declared in the engine, scored, and typed in the app, and nothing ever assigned it, so the score was blind to reserves while the screen beside it said otherwise. The derivation above is what replaced that, it shipped the same day, and a test now pins the rule that the copy and the signal behind it must ship together or neither does. The failures that log success is the general shape of that mistake, and yesterday's piece on AccessGuard is the same discipline applied to a different product: keep what was measured, and say so.

The Short Version

Four places, in order

1. The Payouts page in your admin, in its own words. It outranks everything below. 2. The transaction list, looking for the three reserve-typed entries; the first type means money moved into a reserve, the other two are named and not explained, by Shopify and therefore by anyone honest. 3. The terms' description of a reserve account, once, for what a reserve is for and who sets its terms. 4. Any app, judged by what it does when it is not sure.

And one thing no app does, ours included: prevent a reserve, a hold or a suspension. What a good one can do is tell you what it read, when, and which way it leans when the evidence runs out.

Payout Guard is on the Shopify App Store, with the plain-language version on its page here. The rest of what we make is in seven apps and the problem each one was built for.

BW

Brandon Wigley

Founder of Wigley Studios. Building developer tools since 2018.

Previous: Find the Script Tags on Your Storefront All Articles