Shopify has just expanded the ShopifyPaymentsTransactionType enum in the GraphQL Admin API (version 2026‑10) to include a new CURRENCY_CONVERSION type. This addition lets you retrieve balance‑transaction records that represent currency‑conversion events—something that previously required work‑arounds or manual reconciliation. In this post we’ll break down the change, explain who needs to care, and give you concrete code examples to get up and running fast.
What’s New?
The enum ShopifyPaymentsTransactionType now has the following values: CHARGE, REFUND, PAYOUT, and the newly added CURRENCY_CONVERSION. When you query the shopifyPaymentsBalanceTransactions connection, any transaction that resulted from converting funds between currencies (for example, a payout in USD from a store that sells in EUR) will be returned with type CURRENCY_CONVERSION. The payload includes fields such as originalAmount, convertedAmount, conversionRate, and sourceCurrency/targetCurrency, giving you full visibility into the conversion mechanics.
Who Is Affected?
*Developers*: Anyone building apps, custom reports, or integrations that rely on balance‑transaction data will need to handle the new type. If your code currently assumes the enum only contains CHARGE, REFUND, or PAYOUT, you may see unexpected nulls or errors when a conversion transaction appears.*Merchants*: Indirectly, merchants benefit from more accurate reporting in apps that surface financial data (e.g., accounting integrations). No direct action is required on the storefront side, but they may notice new line items in third‑party dashboards.
How to Use the New CURRENCY_CONVERSION Type
Below is a minimal GraphQL query that pulls the new conversion details. Replace YOUR_SHOP_DOMAIN and the appropriate access token when testing in GraphiQL or your app.
query GetBalanceTransactions {
shop {
shopifyPaymentsBalanceTransactions(first: 20) {
edges {
node {
id
type
amount {
amount
currencyCode
}
... on ShopifyPaymentsBalanceTransactionCurrencyConversion {
originalAmount {
amount
currencyCode
}
convertedAmount {
amount
currencyCode
}
conversionRate
sourceCurrency
targetCurrency
}
}
}
}
}
}
Key points in the snippet:
• The type field will now return CURRENCY_CONVERSION for conversion rows.• The fragment ShopifyPaymentsBalanceTransactionCurrencyConversion exposes the conversion‑specific fields.• You can still request the generic amount field for a quick total, but the detailed breakdown is essential for accounting.
Impact on Merchant Reporting
Many accounting apps pull balance‑transaction data to reconcile payouts. With the conversion type now exposed, those apps can automatically calculate the foreign‑exchange gain or loss without manual entry. If you maintain a custom reporting dashboard, update your data model to store originalAmount, convertedAmount, and conversionRate when type == CURRENCY_CONVERSION.
Next Steps & Best Practices
Conclusion
The addition of the CURRENCY_CONVERSION type is a small but powerful tweak that brings transparency to cross‑currency payouts. By updating your GraphQL queries, handling the new enum safely, and storing the extra fields, you’ll deliver clearer financial data to merchants and keep your integrations future‑proof.
Ready to upgrade? Dive into the official Shopify dev docs, update your API version, and start pulling conversion details today. If you run into challenges, drop a comment below or reach out on the Shopify Community forums.
