Shopify Payments - balanceTransaction vs payouts

GraphQL Admin API Troubleshooting
1

Good afternoon,

I would like to check my understanding of 2 properties the Shopify Payments Account: balanceTransactions and payouts.

Is it true that:

  • while the balanceTransactions contain transactions linking to individual transactions made as part of paying for Orders, the payouts contain information on money paid out by Shopify to the merchant?
  • while there is a many-to-one relationship between a ShopifyPaymentsBalanceTransaction to a payout (see associatedPayout property), there is no way we could map a ShopifyPaymentsPayout “back” to a list of ShopifyPaymentsBalanceTransactionsthat it “covers”?

Thank you,

Piotr

2

Hi @Piotr_Wojcicki! I had a look into this and your understanding is correct. balanceTransactions are the individual line items (charges, refunds, adjustments, etc.) that affect your Shopify Payments balance, while payouts represent the actual money transfers to the merchant’s bank account.

And yes, there’s a many-to-one relationship from balance transactions to payouts via the associatedPayout field.

For the reverse lookup (payout to its balance transactions), you can actually filter balanceTransactions using payments_transfer_id in the query parameter. This isn’t prominently documented but it works. Here’s the pattern:

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

Replace YOUR_PAYOUT_ID with the payout’s numeric ID (you can get this from the legacyResourceId field on the payout, or extract it from the GID). This was covered in a previous thread where folks confirmed it works as expected.