---
title: New guidelines for referenceDocumentUri in inventory adjustments - Shopify developer changelog
description: Shopify’s developer changelog documents all changes to Shopify’s platform. Find the latest news and learn about new platform opportunities.
source_url:
  html: https://shopify.dev/changelog/new-guidelines-for-referencedocumenturi-in-inventory-adjustments
  md: https://shopify.dev/changelog/new-guidelines-for-referencedocumenturi-in-inventory-adjustments.md
---

[Back to Developer changelog](https://shopify.dev/changelog)

August 5, 2025

Tags:

* Admin GraphQL API

# New guidelines for `referenceDocumentUri` in inventory adjustments

We've released new guidelines and updated documentation for the [`referenceDocumentUri`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/inventoryAdjustQuantities#arguments-input.fields.referenceDocumentUri) field in [inventory adjustment mutations](https://shopify.dev/docs/api/admin-graphql/latest/mutations/inventoryAdjustQuantities). By following these guidelines, your apps can maintain inventory traceability, which helps merchants troubleshoot issues and conduct audits more easily. Access the field in admin via the "Inventory adjustment changes" report in Analytics or on the Adjustment History Page.

**What’s new:**

* Detailed guidelines for using the `referenceDocumentUri` field to link each inventory adjustment to its source system and document.
* Recommendations for adopting the Global ID (GID) format (`gid://namespace/entity/id`) to maintain consistency across integrations.
* Support for various URI formats, including URLs and custom schemes, ensuring backward compatibility.
* Best practices for defining namespaces and entity types.
* Code examples for Warehouse Management Systems (WMS), Third-Party Logistics (3PL), Point of Sale (POS), and Enterprise Resource Planning (ERP) integrations.
* Migration guides for updating existing implementations.
* Validation rules and format specifications.

**These updates enable you to:**

* Provide merchants with comprehensive audit trails for compliance.
* Display your app’s name in Shopify admin inventory history.
* Trace inventory changes back to their origin, simplifying troubleshooting.

To implement, you'll incorporate the `referenceDocumentUri` field into the [`inventoryAdjustQuantities` mutation](https://shopify.dev/docs/api/admin-graphql/latest/mutations/inventoryAdjustQuantities).

[Explore the updated guidelines and documentation](https://shopify.dev/docs/apps/build/orders-fulfillment/inventory-management-apps)

![](https://screenshot.click/31-17-gbq55-o3ax8.png)

![](https://screenshot.click/31-18-jrogx-a5slu.png)