---
title: "Shopify Payments: Payouts, Chargebacks and the API Explained"
description: "How Shopify Payments works for finance and engineering teams: payouts, the payout schedule, chargebacks, the GraphQL API and when you need another gateway."
url: "https://no7software.co.uk/blog/shopify-payments-payouts-extensions-architecture"
last_modified: "2026-11-13"
---

# Shopify Payments: Payouts, Chargebacks and the API Explained

## Key takeaways

- Shopify Payments collects card and wallet sales into a balance, then pays that balance to your bank on a daily, weekly, monthly or manual payout schedule.
- Payouts, chargebacks and balance transactions are all read through the shopifyPaymentsAccount query in the GraphQL Admin API.
- Reading the account needs the read_shopify_payments or read_shopify_payments_accounts scope, and reading payouts also needs the view_payouts user permission.
- A payout only contains the balance transactions available when it was issued, so match lines to a payout by the payout, never by calendar date.
- The REST Admin API has been legacy since 1 October 2024. Keep existing REST payout jobs running and build new ones on GraphQL.
- A Payment Customization Function can rename, reorder or hide payment methods and set payment terms without any new payment provider.
- Custom payments extensions are limited to eligible Shopify Plus merchants and can only be built by approved Partners.

**Shopify Payments** is Shopify's own payment processor, and its payouts, disputes and balance are readable through one query in the GraphQL Admin API: `shopifyPaymentsAccount`. Most stores that ask for a custom gateway need three smaller things first: a payout reconciliation job, a dispute feed and a checkout rule. Only the fourth option, a custom payments extension, is limited to eligible Shopify Plus merchants and has to be built by an approved Partner.

This guide explains how the money moves, then walks through each of the four in the order you should scope them, with the queries we would start from.

## How does Shopify Payments work?

Card and wallet payments taken through Shopify Payments build up as a balance on the store's Shopify Payments account. Shopify sends that balance to the connected bank account as payouts, on the account's payout schedule. Refunds, fees and disputes are recorded against the same balance, so a payout is a net figure and not the gross sales of the days it covers. Everything below is a way of reading one of those three things: the balance, the payouts or the disputes.

## What does the Shopify Payments API expose?

The [ShopifyPaymentsAccount object](https://shopify.dev/docs/api/admin-graphql/latest/objects/ShopifyPaymentsAccount) holds the financial account behind a store. Reading it requires the `read_shopify_payments` or the `read_shopify_payments_accounts` access scope. These are the fields a finance or operations integration uses most:

| Field | What you use it for |
| --- | --- |
| `payouts` | Each transfer between the Shopify Payments balance and the bank account |
| `balanceTransactions` | The individual charges, refunds and adjustments that change the balance |
| `disputes` | Chargebacks and inquiries, with their status and evidence deadlines |
| `payoutSchedule` | The interval, and the weekly or monthly anchor day, on which payouts are sent |
| `bankAccounts` | The bank accounts that payouts are sent to |
| `balance`, `defaultCurrency`, `country` | The current balance and the account's currency and country |
| `chargeStatementDescriptors` | The text customers see on their card statement |

Payouts and disputes are both paginated connections that accept a search query, so a nightly job can page through them instead of exporting CSV files from the admin.

## How do you read Shopify payouts with the GraphQL API?

**A Shopify Payments payout** is a transfer of funds between a merchant's Shopify Payments balance and their bank account. The [ShopifyPaymentsPayout object](https://shopify.dev/docs/api/admin-graphql/latest/objects/ShopifyPaymentsPayout) adds one requirement on top of the app scope: the user must have the `view_payouts` permission. A query like this returns the newest payouts with the figures a ledger needs:

```
query RecentPayouts {
  shopifyPaymentsAccount {
    payouts(first: 20, reverse: true) {
      nodes {
        id
        issuedAt
        status
        transactionType
        net { amount currencyCode }
        summary {
          chargesGross { amount }
          chargesFee { amount }
          refundsFeeGross { amount }
          adjustmentsGross { amount }
          adjustmentsFee { amount }
        }
      }
    }
  }
}
```

The `summary` breaks fees and gross amounts down by transaction type, so you can post charges, refunds and adjustments to separate ledger accounts without reading every line. `transactionType` is `DEPOSIT` when money moves to the bank and `WITHDRAWAL` when it moves back to Shopify Payments. The status tells you whether the money has landed:

| Payout status | Meaning in Shopify's documentation |
| --- | --- |
| `SCHEDULED` | Created with transactions assigned, but not yet submitted to the bank |
| `PAID` | Successfully deposited into the bank |
| `FAILED` | Declined by the bank |
| `CANCELED` | Cancelled by Shopify |

`IN_TRANSIT` still appears in the enum but is marked as deprecated, so do not build new logic on it. Treat `FAILED` and `CANCELED` as exceptions a person should look at, not as rows to retry.

## How does the Shopify payout schedule work?

The [payoutSchedule](https://shopify.dev/docs/api/admin-graphql/latest/objects/ShopifyPaymentsPayoutSchedule) on the account has three fields: an `interval`, a `weeklyAnchor` and a `monthlyAnchor`. The interval takes one of four values:

| Interval | When payouts are sent |
| --- | --- |
| `DAILY` | Each business day |
| `WEEKLY` | Each week, on the `weeklyAnchor` day, which can be any weekday from Monday to Friday |
| `MONTHLY` | Each month, on the `monthlyAnchor` day. A payout scheduled for the 29th to the 31st is sent on the last day of a shorter month |
| `MANUAL` | Payouts are not made automatically |

Read the schedule from the API and feed it to your cash-flow forecast, so the forecast follows the setting the store actually has and not the one someone remembers choosing.

## How do you reconcile a Shopify payout to its balance transactions?

**A balance transaction** is a single movement on the Shopify Payments balance: a charge, a refund or an adjustment. Shopify documents one detail on the payout's `issuedAt` field that decides how you match them: the payout only contains balance transactions that were available at that time. A sale taken after the payout was issued belongs to a later payout, even when it shares a calendar day with the first one.

Our advice follows from that: match lines to a payout by the payout itself and never by date. The `balanceTransactions` connection lists `payments_transfer_id`, `payout_date` and `payout_status` among its query filters, and every line carries an `associatedPayout` with an ID and a status:

```
query PayoutLines {
  shopifyPaymentsAccount {
    balanceTransactions(first: 100, query: "payments_transfer_id:PAYOUT_ID") {
      nodes {
        id
        type
        sourceType
        transactionDate
        amount { amount currencyCode }
        fee { amount }
        net { amount }
        associatedPayout { id status }
      }
      pageInfo { hasNextPage endCursor }
    }
  }
}
```

Replace `PAYOUT_ID` with the payout you are checking, and confirm the filter against one payout you have already reconciled by hand before you automate it. Then run two checks. The `net` amounts of the lines should add up to the payout's `net`. The fees should add up to the fee totals in the payout's `summary`. If either check fails, keep paging with `endCursor` before you raise an exception.

If your money does not all land in one Shopify bank account, for example on a marketplace that pays sellers, the same matching problem is covered from the platform side in [Stripe Connect marketplace payments engineering](https://no7software.co.uk/blog/stripe-connect-marketplace-payments-engineering).

## Should you still use the REST payout endpoints?

Only for integrations that already run on them. Shopify's [REST payouts reference](https://shopify.dev/docs/api/admin-rest/latest/resources/payouts) states that the REST Admin API is a legacy API as of 1 October 2024. From 1 April 2025, all new public apps must be built exclusively with the GraphQL Admin API.

The REST resources are still documented for the 2026-10 version. `shopify_payments/payouts.json` lists payouts and accepts a `date_max` filter. `shopify_payments/balance/transactions.json` returns balance transactions ordered by processing time, most recent first, and accepts a `payout_id` filter. `shopify_payments/disputes.json` returns disputes newest first and can filter by status, for example `status=won`. Leave a working REST job alone until you have time to move it, and write anything new against GraphQL.

## How do you track Shopify chargebacks and disputes?

Disputes hang off the same account object as payouts, so one token and one worker can cover both. Each [ShopifyPaymentsDispute](https://shopify.dev/docs/api/admin-graphql/latest/objects/ShopifyPaymentsDispute) carries a `status`, a `type`, an `amount`, the related `order`, `reasonDetails` and four dates: `initiatedAt`, `evidenceDueBy`, `evidenceSentOn` and `finalizedOn`.

The date that costs money is `evidenceDueBy`. Send an alert to whoever answers disputes when a new one appears, and a second alert a few days before that deadline if `evidenceSentOn` is still empty. On the accounting side, the payout summary describes `adjustmentsFee` as the total fees for all adjustments including disputes, which is where dispute costs show up when you post a payout.

## What can you change at checkout without a payments extension?

More than most teams expect. The [Payment Customization Function API](https://shopify.dev/docs/api/functions/latest/payment-customization) lets you rename, reorder or hide the payment methods offered at checkout, set payment terms and add a review requirement to an order. The methods it covers include credit cards, gift cards, store credit and wallets such as Shop Pay, Apple Pay and Google Pay. Payment terms let a buyer pay at a later date, and can be fixed, net or event-based, with an optional deposit.

What you should not do is rebuild payment choice in the interface. Shopify's guidance for [checkout UI extensions on payment targets](https://shopify.dev/docs/api/checkout-ui-extensions/latest/targets/checkout/payment) is clear on two points. Extensions there can read the available and selected payment methods but cannot modify the list. Adding buttons, form fields or selection controls can confuse buyers about where to complete their payment. Put the rule in a Function and use the UI target for information only. Wallet buttons on a custom storefront are a separate job, which we cover in [wiring Apple Pay and Google Pay into headless Shopify](https://no7software.co.uk/blog/apple-pay-google-pay-headless-shopify-wiring).

## When do you need a third-party Shopify payment gateway?

When the payment itself has to be processed somewhere else. [Payments extensions](https://shopify.dev/docs/apps/build/payments) integrate with the Shopify admin and checkout to provide payment processing for merchants. They can take credit card payments on the checkout or send the buyer to an app-hosted or offsite page, and the credit card type supports 3D Secure authentication.

Two conditions apply, and both are worth confirming before anyone writes a specification. Only approved Partners can build payments extensions on Shopify's Payments Platform. And the option to build a custom one is limited to eligible Shopify Plus merchants, with Shopify Plus Support confirming eligibility. If the plan is the open question, start with [Shopify vs Shopify Plus](https://no7software.co.uk/compare/shopify-vs-shopify-plus). If the processor is, our [comparison of Adyen and Stripe for UK Plus stores](https://no7software.co.uk/blog/adyen-vs-stripe-uk-plus-payment-guide) covers the commercial side and [Strong Customer Authentication and 3DS2 engineering](https://no7software.co.uk/blog/strong-customer-authentication-3ds2-engineering) covers the challenge flow.

### Worked example: a wholesale store on net terms

A store sells to trade customers on net terms and to the public by card. Finance wants payouts matched in the accounting system, and the wholesale team wants one regional pay-by-bank method. Taken one requirement at a time:

| Requirement | Shopify tool | Payments extension needed? |
| --- | --- | --- |
| Hide Apple Pay and Google Pay on trade orders | Payment Customization Function | No |
| Offer net payment terms with a deposit | Payment Customization Function | No |
| Match every payout to its charges and refunds | `payouts` and `balanceTransactions` queries | No |
| Alert on chargebacks before evidence is due | `disputes` query | No |
| Add the regional pay-by-bank method | Offsite payments extension | Yes: approved Partner, eligible Plus merchant |

Four of the five requirements need no new payment provider. Only the last one justifies gateway work, and it should be scoped on its own.

## Your next three moves

1. **Check scopes and permissions**: confirm your app holds `read_shopify_payments` or `read_shopify_payments_accounts`, and that the user behind the token has `view_payouts`. Run the payouts query above against your own store.
2. **Reconcile one payout by hand**: pull its balance transactions, add up the net amounts and compare the total with the payout. Automate the job once the two figures agree.
3. **List your checkout rules**: write down every payment rule you want, then mark which ones a Payment Customization Function covers. What is left is your real gateway requirement.

If the list still ends with a custom payments extension or a payout pipeline you would rather not build yourself, our [Shopify development](https://no7software.co.uk/shopify-development) team can scope it with you.

## Frequently Asked Questions

The questions buyers and engineers ask us most about this topic.

### How often does Shopify Payments pay out?

It depends on the payout schedule set on the account. The schedule interval can be daily (each business day), weekly on a chosen weekday from Monday to Friday, monthly on a chosen day of the month, or manual, where payouts are not made automatically. You can read the current setting from the payoutSchedule field of shopifyPaymentsAccount.

### How do I get Shopify Payments payouts from the API?

Query shopifyPaymentsAccount in the GraphQL Admin API and read its payouts connection. Each payout returns an ID, the time it was issued, a net amount, a status, a transaction type and a summary of fees and gross amounts. The app needs the read_shopify_payments or read_shopify_payments_accounts scope, and the user needs the view_payouts permission.

### How do I match a Shopify payout to individual orders?

Read the balanceTransactions connection on the same account and filter it to one payout, or check the associatedPayout on each line. Shopify documents that a payout only contains the balance transactions available when it was issued, so match by payout and not by date. The net amounts of the lines should add up to the payout's net amount.

### Is the Shopify REST payouts API deprecated?

Shopify describes the REST Admin API as a legacy API as of 1 October 2024, and since 1 April 2025 new public apps must be built exclusively with the GraphQL Admin API. The REST payout, dispute and balance transaction resources are still documented for the 2026-10 version, so existing integrations keep working, but new work should use GraphQL.

### Who can build a custom payment extension on Shopify?

Only approved Partners can build payments extensions on Shopify's Payments Platform, and the option to build a custom one is limited to eligible Shopify Plus merchants. Shopify Plus Support confirms eligibility.

### What can you change at checkout without building a custom payment extension?

With the Payment Customization Function API you can rename, reorder or hide payment methods such as credit cards, gift cards, store credit, Shop Pay, Apple Pay and Google Pay. You can also set fixed, net or event-based payment terms with an optional deposit and add an order review requirement.