I’m a Shopify app developer, and I have a question regarding the deprecation of the authorizationCode field on the OrderTransaction object in the Admin GraphQL API.

GraphQL Admin API Troubleshooting
,
1

According to the Shopify changelog:

we are advised to migrate from authorizationCode to paymentId. However, there are some important differences in how these fields are used in our current integration that we would like to clarify.

1. Using authorizationCode to reconcile Stripe payments

Currently, we use Shopify’s OrderTransaction.authorizationCode to deduplicate and reconcile payments against Stripe.

Specifically, we match Shopify’s authorizationCode with the corresponding authorization identifier received from Stripe.

The new paymentId value is different from the existing authorizationCode value, so it does not provide the same identifier we currently use to match Shopify transactions with the corresponding Stripe authorization.

After authorizationCode is fully removed, will there be any field or supported mechanism in the Admin GraphQL API to retrieve the gateway’s original authorization/charge identifier corresponding to the Stripe transaction?

2. Using paymentId to identify Stripe transactions

Our integration also currently uses paymentId to identify and distinguish Stripe-related transactions, including refund transactions.

In particular, the value of paymentId can contain the underlying Stripe transaction identifier, which our integration uses to determine whether a Shopify Payments transaction corresponds to a Stripe transaction or refund.

We would therefore like to clarify whether using paymentId for identifying the corresponding Stripe transaction or refund is an officially supported and reliable approach.

If this behavior is expected to continue, is the Stripe transaction/refund identifier contained in paymentId considered stable and safe for apps to use for reconciliation and transaction identification?

3. Stability and uniqueness of paymentId

Is paymentId guaranteed to be unique and stable across retries, partial captures, refunds, and other related transactions for the same underlying payment authorization?

For example, can multiple OrderTransaction records associated with the same payment/authorization have different paymentId values, or is paymentId intended to consistently identify the underlying payment across related transactions?

4. Recommended migration strategy

For apps that currently rely on authorizationCode for deduplication and reconciliation against gateway data, what migration strategy does Shopify recommend?

We would appreciate any detailed guidance or best-practice recommendation for replacing our current authorizationCode-based deduplication and reconciliation logic, especially for integrations involving Shopify Payments and Stripe.

In particular, it would be helpful to understand whether paymentId is intended to be the canonical replacement for authorizationCode, including for identifying the corresponding Stripe payment/refund transaction, or whether there is another recommended identifier or workflow that apps should use.

Thank you for your help.

Best regards,
Mahesh Kori

2

Hi @Mahesh_kori, you’re right that paymentId doesn’t carry the same value as authorizationCode.

  1. There’s no documented field or mechanism today for retrieving the gateway’s original Stripe authorization or charge identifier. The changelog is explicit that paymentId returns a Shopify-specific identifier, which differs from the provider-specific value in authorizationCode. It doesn’t describe anything that maps back to Stripe’s IDs.

  2. I wouldn’t build on provider identifiers appearing inside paymentId. They aren’t a documented or supported contract, so I can’t call matching on them reliable. The same caution applies to receiptJson, whose field description states it’s gateway-specific, not a stable contract, and apps shouldn’t parse or rely on it for business logic.

  3. There’s no documented uniqueness or stability guarantee across retries, partial captures, and refunds, so I’d avoid assuming related transactions share one paymentId or that each gets a distinct one. For Shopify-side identity, use id on OrderTransaction, which is globally unique per transaction record, and parentTransaction for the authorization/capture relationship.

  4. The supported migration is the one the changelog recommends, updating your queries and stored reconciliation formats to paymentId as the Shopify-side identifier.

For the Stripe-side join specifically, I’m checking with the team whether a supported way to retrieve the original Stripe identifiers exists and what guarantees apply across related transactions. I’ll follow up here once I hear back from them. Thanks for raising your questions here!

4

Hi @Mahesh_kori, thanks for waiting to hear back from me! I checked with the team to confirm, and the answer is no, there’s no supported way to retrieve the original Stripe authorization, charge, or refund ID once authorizationCode is deprecated. The paymentId field is the intended replacement, and reconciliation should move to it as the Shopify-side reference.

On the guarantees, treat paymentId as an opaque reference that can be null. It isn’t guaranteed to be unique, and it isn’t guaranteed to be shared across every transaction for a payment. Captures, refunds, and voids can carry their own value, and depending on how the payment was processed, some related transactions may share one. Match each transaction on its own paymentId and use parentTransaction to link captures and refunds back to the original payment. Don’t assume one paymentId covers retries, multiple captures, or refunds.

I’ve shared feedback that a supported way to reference the original provider IDs would help with reconciliation, so thanks for raising this here!