In the REST Admin API, the /admin/api/<api_version>/shopify_payments/balance/transactions endpoint supports querying balance transactions associated with a specific payout_id.
Currently, there is no equivalent payout_id query field available in the GraphQL Admin API’s shopifyPaymentsAccount.balanceTransactions. This limitation makes it impossible to fetch balance transactions tied to a specific payout_id using GraphQL.
Request
As the REST Admin API is being deprecated, please add payout_id to the query of shopifyPaymentsAccount.balanceTransactions.
Hi Liam, I think it does but it seems impossible to use the associatedPayout in the query. See below a GraphQL response I just received.
{"data":{"shopifyPaymentsAccount":{"balanceTransactions":{"nodes":[]}}},"extensions":{"cost":{"requestedQueryCost":36,"actualQueryCost":3,"throttleStatus":{"maximumAvailable":2000.0,"currentlyAvailable":1997,"restoreRate":100.0}},"search":[{"path":["shopifyPaymentsAccount","balanceTransactions"],"query":"associatedPayout:gid://shopify/ShopifyPaymentsPayout/74170105928","parsed":{"and":[{"field":"default","match_all":"//shopify/ShopifyPaymentsPayout/74170105928"},{"field":"associatedPayout","match_all":"gid"}]},"warnings":[{"field":"associatedPayout","message":"Invalid search field for this query."}]}]}}
Thanks for explaining this situation - it does appear to be a limitation that doesn’t exist on REST. I’ve reached out to the relevant team and will update here on their recommendation.
I have connected with the payments team on this and they’ve confirmed it is a gap in the GraphQL API currently and will be addressing it. I don’t have an ETA to share on when this will be available however.
Is there a timeline on when the Payouts REST API will stop working? Being able to query by associated payout is critical for our process, so we need to know if the REST API will be available at least until the ability to query is added.
There’s no available deadline yet for the deprecation but this will be supported in GraphQL before REST is deprecated (so you’ll have time to migrate fully).
I spent the weekend attempting to migrate the REST Admin API endpoint: admin/api/2024-01/shopify_payments/balance/transactions.json?limit=250&payout_id=xxx
Fairly quickly come to realize that it may be impossible to filter equivalent GraphQL endpoints with a payout_id. Similar errors seen as the above comments.
Just posting here to mention that there are others looking for this same update. The ability to filter by Payout ID is an absolute requirement. We also have concerns with the Admin API deprecation. Many many companies rely on this payout information for the accounting side of the businesses.
For me using the ‘payments_transfer_id’ filter works. For example
query {
shopifyPaymentsAccount {
balanceTransactions(first:100, query: "payments_transfer_id:payout_id", reverse:true, hideTransfers: true)
{
nodes{
id
type,
adjustmentReason,
adjustmentsOrders{
name,
amount{
amount
}
orderTransactionId
}
sourceType,
amount{
amount
}
associatedOrder{
id
name
}
associatedPayout{
id
}
fee{
amount
}
net{
amount
}
sourceId,
sourceOrderTransactionId
test
}
}
}
}
I didn’t use the full gid, rather I used only the last segment. (In your example I didn’t use gid://shopify/ShopifyPaymentsPayout/74170105928 rather I used only 74170105928) so you can replace my query string with the following query: "payments_transfer_id:74170105928"
@SRCB How did you come to that conclusion since we can’t find “payments_transfer_id” in the documentation?
EDIT: We do find “payments_transfer_id” as a shopifyPaymentsAccount.balanceTransaction query parameter but it doesn’t say that it searches on the balanceTransaction.id.
@Sharespine I figured that there would be some type of filter for the payout ID, and having used the Shopify GraphQL APIs for a while, I have already seen that the filter name and the field name don’t always match, so I tested out all the filters. My test for payments_transfer_id showed that it returned all the transactions that the REST endpoint returned, and none that it didn’t.
As for being 100% sure that this is the intended use? In fact I am not 100% sure, I am only 99% sure, this was one of the reasons I posted it here, I wanted someone from Shopify to confirm that it is indeed the intended use. And yes the documentation should indeed be updated to show exactly which field it is referencing (as is done here, where the field & filter names don’t match, and there is a link to exactly what is being referenced.)
Thanks for the workaround! It’s a bit scary to use it as it’s not documented. I hope we can get a fix for this soon or at least a confirmation that payments_transfer_id is okay to use.
@Shopify: Is it possible to get Shopify confirmation that the code example supplied by SRCB in this thread does work and will continue to work?
We have tested it and it works now but since @Liam-Shopify confirmed on Jan 17 that this was a gap in the GraphQL functionality it’s hard to know what to make of it?
Since the changes we make now will affect hundreds of customers we want to get it right (both now and for the future).