I received the attached email regarding the March 16, 2026 PayPal integration update, which mentions that the receiptJson field structure (keys, nesting, and values) will change for PayPal orders.
Hey @jribeiro, I would suggest taking a look at our January 2026 changelog for another update regarding this field. It recommends moving away from receiptJson since the field is gateway-defined and its structure can change without being treated as a breaking API change.
Based on the email you shared, I’d expect that screenshot to be an accurate preview of what the updated data will look like after the migration.
That said, what fields from receiptJson are you currently using in your workflows? The changelog mentions the stable alternative OrderTransaction object. Depending on what you need, that might be a more reliable long-term option.
I understand that this change is being driven by PayPal and that Shopify may not have full control over it. I’d like to get more details about the scope and impact so I can assess how it will affect our application.
Specifically, we rely on some fields in the receiptJson that are not currently exposed through the Shopify Admin API, including:
gift_card_id
pp_ref
network_transaction_id
At the moment we are parsing the following fields from the receiptJson:
parent_transaction_id
payment_id
gift_card_id
pp_ref
network_transaction_id
Can you clarify whether these fields will continue to be available after the change on March 16, 2026, or if there are planned replacements? Any additional documentation or details about what will be removed or altered would be very helpful.
For gift_card_id, it’s not directly on the OrderTransaction object, so it’s a bit more roundabout. The GiftCardTransaction interface has a giftCard field with an order connection you can use to get the ID. More cumbersome than a single field on the receipt, but stable.
For pp_ref and network_transaction_id, can you share what you’re using those for in your workflows? If I understand the business purpose, I can help identify the right replacement fields.
As the email itself mentions, receiptJson is not a stable contract and its structure can change without notice, so ideally we’d get your integration off that field entirely before the migration.
I use the pp_ref field in my system to match some PayPal payments. In certain cases, I treat this value as the PayPal payment ID. Similarly, I use network_transaction_id for comparable purposes with Braintree transactions.
Do you know whether these identifiers (or equivalent PayPal and Braintree transaction IDs) are available anywhere in the Shopify API? If so, could you point me to the relevant resource or field?
Where are you doing the reconciliation? Within Shopify (matching transactions to orders or refunds), or against an external system like PayPal’s or Braintree’s own reporting?
The reason I ask, paymentId is our standardized payment identifier across all gateways, consistent through the full transaction lifecycle. If you’re reconciling within Shopify, it may make the gateway-specific IDs unnecessary entirely.
If you do need to reconcile against PayPal’s or Braintree’s external systems, it’s worth checking what value paymentId actually returns on those transactions. It may reference the same ID you’re used to working with.
Hi Kyle, unfortunately, I’m reconciling directly against the PayPal and Braintree API data, not within Shopify.
So the reconciliation is based on the gateway-reported transactions and IDs from their systems, rather than matching transactions to orders or refunds inside Shopify.
That’s the reason I was initially using the pp_ref and network_id fields. I did not find the shopify paymentIdat those APIs. Let me take a deeper look at that!
Thanks for flagging the paymentId and let me know that this is a standard across all shopify data!
@KyleG-Shopify
For the PayPal gateway, we are currently parsing the fee_amount value from receiptJson.
Could you please clarify whether the fee_amount field will continue to be available in a different field after the changes on March 16, 2026, or if we will still need to use receiptJson?
For provider-specific details that aren’t available as typed fields like pp_ref, network_transaction_id, fee_amount I think it’s best we all lean in to the recommendations from the January 2026 changelog instead of trying to identify what may and may not be changing with the payload send from Paypal.
If you require provider-specific details that aren’t available as typed fields, fetch them directly from the payment provider (when applicable) and store only the minimal data your system needs.
