---
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/posts/new-guidelines-for-referencedocumenturi-in-inventory-adjustments
  md: >-
    https://shopify.dev/changelog/posts/new-guidelines-for-referencedocumenturi-in-inventory-adjustments.md
metadata:
  effectiveApiVersion: ''
  affectedApi:
    - displayName: Admin GraphQL API
      handle: admin-graphql
  primaryTag:
    displayName: API
    handle: api
  secondaryTag:
    displayName: Update
    handle: update
  indicatesActionRequired: false
  createdAt: '2025-07-25T13:27:14-04:00'
  postedAt: '2025-08-05T08:36:00-04:00'
  updatedAt: '2025-08-05T08:35:18-04:00'
  effectiveAt: '2025-07-26T12:00:00-04:00'
---

August 5, 2025

# New guidelines for `referenceDocumentUri` in inventory adjustments

DateAugust 5, 2025

FlagsUpdate

SurfacesAPI

Affected APIs[Admin GraphQL API](https://shopify.dev/changelog?api_type=admin-graphql)

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)