Understanding the New CURRENCY_CONVERSION Type in Shopify Payments Balance Transactions

Shopify’s GraphQL Admin API now includes a CURRENCY_CONVERSION transaction type, letting developers fetch detailed conversion data directly from balance transactions. Learn what changed, who it affects, and how to adapt your integrations.

Understanding the New CURRENCY_CONVERSION Type in Shopify Payments Balance Transactions
6 sections

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

  • Update Your GraphQL Version – Ensure your app targets at least API version 2026‑10. Older versions will not recognize the new enum value.
  • Add Defensive Enum Handling – In strongly‑typed languages, extend your enum definition and add a fallback case (e.g., UNKNOWN) to avoid runtime crashes when new types appear in the future.
  • Store Conversion Metadata – Persist originalAmount and convertedAmount separately. This makes it trivial to generate FX‑gain reports for tax filing.
  • Test with Multi‑Currency Stores – If your store sells in multiple currencies, trigger a conversion by creating a test order in a foreign currency and processing a payout. Verify the CURRENCY_CONVERSION node appears as expected.
  • Communicate Changes to Stakeholders – Let merchants know that their financial dashboards will now show conversion line items, reducing confusion around “extra” fees.
  • 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.

    Tags
    Sources

    Related Articles

    Admin‑Created Custom Apps Now Live in the Shopify Dev Dashboard

    Admin‑Created Custom Apps Now Live in the Shopify Dev Dashboard

    Shopify now surfaces custom apps built in the admin inside the Dev Dashboard, giving developers centralized credential control, IP allowlisting, and full API/webhook logs. Learn what changed, who’s affected, and how to secure and monitor your apps today.

    November 17, 20265 min
    Amazon EventBridge Webhook Payloads Now Up to 1 MB – What It Means for Your Shopify Apps

    Amazon EventBridge Webhook Payloads Now Up to 1 MB – What It Means for Your Shopify Apps

    Shopify increased the Amazon EventBridge webhook payload limit from 256 KB to 1 MB, letting developers receive larger product and order data inline. Learn who is affected, how it works, and what steps to take now.

    November 17, 20265 min
    Understanding the New B2B Location Access Rules in Shopify’s Customer Account API

    Understanding the New B2B Location Access Rules in Shopify’s Customer Account API

    Shopify’s latest API update tightens B2B location data access, limiting what customers can see to their own company information and orders. Learn what changed, who’s affected, and how to adapt your apps.

    November 17, 20266 min
    Unlock Custom Data Insights: Sidekick Now Analyzes Metafields & Metaobjects

    Unlock Custom Data Insights: Sidekick Now Analyzes Metafields & Metaobjects

    Sidekick can now read your store’s custom metafields and metaobjects, letting merchants ask analytics questions about fabric, supplier, designer and more. Learn what changed, who it affects, and how to start using this feature today.

    November 17, 20265 min