Reconciliation between payouts and balance transactions

GraphQL Admin API Troubleshooting
1

Our application is polling both ShopifyPaymentsPayout and ShopifyPaymentsBalanceTransaction data from the GraphQL API and we have found cases where ShopifyPaymentsPayout is created/updated but the ShopifyPaymentsBalanceTransaction related to the update are not available in the API. In some cases the ShopifyPaymentsBalanceTransactions were made available hours and even a day after. Has anyone experienced this? What is the expectations in terms of when the ShopifyPaymentsBalanceTransactions are made available in the API?

For now we have added some reconciliation logic every time the payout status changes to reload all the ShopifyPaymentsBalanceTransactions associated to it but this is very compute intensive and I would like to understand better what is going on in the API so we can implement a robust solution.

1 Like
2

Hey @Mathieu_Nunez! Nice to hear from you again! I’ll take a look in to this. Can you confirm that a balance transaction has been created at the same time as the payout?

One way to check this is to see if the transactionDate field aligns with the payout time or if it’s different.

This is just a hunch (and I’ll look in to this to confirm), but the reason may be that there’s a time delay in actually processing the transaction after the payout is created, resulting in the delay you are seeing.

I’ll follow up here once I know more.

4

@KyleG-Shopify thank you for looking into this. I am not 100% sure when the balance transaction was created but it was definitely not available in the API when the payout came in as our application reloads all the balance transactions related to the payout and it was still missing. Let me know if you find anything.

5

Hey Mathieu,

Thanks for those details. I conveniently had a payout in my own store yesterday so I am querying that to get a better understanding here.

I did find that in my case, the payout (looking at our database record) was created 2 seconds after the transfer transactionDate so that doesn’t match what you are seeing with a payout and no transaction.

Digging in to this further, it is typically expected for payouts to be created based on the cadence the merchant has set up in their Shopify Payment settings, with some exceptions for delayed transactions (outlined here: https://help.shopify.com/en/manual/payments/shopify-payments/payouts/understanding-payout-delays )

When you look at the balanceTransactions that were delayed, are you noticing this with specifically the TRANSFER type, or is it consistent with any other type? Can you tell if any of the above mentioned delays occurred with these payouts?

This is the query I ran if it helps with the context on what I am looking at:

query ShopifyPaymentsAccount {
    shopifyPaymentsAccount {
        balanceTransactions(first: 2, reverse: true) {
            nodes {
                type
                transactionDate
                associatedPayout {
                    id
                }
            }
        }
        payouts(first: 1, reverse: true) {
            nodes {
                issuedAt
                id
            }
        }
    }
}

Which returned:

{
    "data": {
        "shopifyPaymentsAccount": {
            "balanceTransactions": {
                "nodes": [
                    {
                        "type": "TRANSFER",
                        "transactionDate": "2025-09-22T00:05:27Z",
                        "associatedPayout": {
                            "id": "gid://shopify/ShopifyPaymentsPayout/******360"
                        }
                    },
                    {
                        "type": "CHARGE",
                        "transactionDate": "2025-09-18T20:32:28Z",
                        "associatedPayout": {
                            "id": "gid://shopify/ShopifyPaymentsPayout/******360"
                        }
                    }
                ]
            },
            "payouts": {
                "nodes": [
                    {
                        "issuedAt": "2025-09-23T00:00:00Z",
                        "id": "gid://shopify/ShopifyPaymentsPayout/******360"
                    }
                ]
            }
        }
    }
6

Hi @KyleG-Shopify. We do expect delays for the balanceTransaction type TRANSFER so this is not a problem for us the issue is we found balanceTransactions of type CHARGE which were delayed. I will try to find an example today but it is quite difficult as this is a transient issue.