Replace Shopify’s inventoryBulkAdjustQuantityAtLocation with inventoryAdjustQuantities: complete migration guide for developers

Table of Contents

1. Key Highlights
2. Introduction
3. Why Shopify consolidated inventory mutations
4. What inventoryAdjustQuantities does and how it differs
5. Syntax and example requests
6. Step-by-step migration checklist
7. How to build the input payload correctly
8. Resolving inventoryItemId and locationId
9. Handling partial failures and userErrors
10. Idempotency and duplicate handling
11. Concurrency and race conditions
12. Rate limiting and GraphQL cost management
13. Auditing and reconciliation best practices
14. Monitoring and alerts
15. Sample implementations
16. Real-world migration scenarios
17. Common migration pitfalls and how to avoid them
18. Testing and rollout strategy
19. Operational considerations for integrations
20. Logging and observability recommendations
21. When to keep running the old mutation during transition
22. Frequently encountered userErrors and responses
23. Best practices checklist (summary)
24. FAQ

Key Highlights

• Shopify will remove the inventoryBulkAdjustQuantityAtLocation GraphQL mutation; migrate to inventoryAdjustQuantities to keep inventory adjustments functional and consistent across multiple items and locations.
• The new inventoryAdjustQuantities mutation centralizes changes into an inventoryAdjustmentGroup with richer metadata (reason, name, referenceDocumentUri) and supports batched changes across items and locations—update code, add robust error handling, and test reconciliation workflows.

Introduction

Shopify has announced the deprecation and removal of the inventoryBulkAdjustQuantityAtLocation mutation from the Admin GraphQL API. Any app still calling that mutation will stop making inventory adjustments once the endpoint is removed. The replacement is inventoryAdjustQuantities, a single, more structured mutation that records grouped adjustments with contextual metadata and supports multiple items and locations at once.

This change affects inventory integrations, point-of-sale connectors, warehouse management systems, and internal back‑office tools that perform stock corrections, transfer reconciliations, or automated fulfillment adjustments. The migration requires code updates, attention to error handling and idempotency, and operational testing to ensure inventory consistency. This guide explains what to change, why it matters, and how to implement a safe, production-ready migration.

Why Shopify consolidated inventory mutations

The new mutation replaces a targeted, location-scoped bulk adjust call with a general, multi-item change operation. Consolidating inventory operations into inventoryAdjustQuantities delivers several practical benefits:

• A single, consistent API for multi-item, multi-location adjustments reduces client complexity.
• Inventory changes are grouped into an inventoryAdjustmentGroup, making audit trails and reconciliation simpler.
• Additional metadata fields—reason, name, and referenceDocumentUri—improve traceability between inventory actions and internal systems (warehouse manifests, audit logs, accounting entries).

For developers, this means a small upfront engineering effort in exchange for clearer, auditable inventory operations and fewer special-case implementations.

What inventoryAdjustQuantities does and how it differs

inventoryAdjustQuantities accepts an InventoryAdjustQuantitiesInput object and returns an inventoryAdjustmentGroup ID that represents the logical unit of work. Each change in the input includes a delta (positive to increase, negative to decrease), an inventoryItemId, and a locationId. The mutation records additional metadata the caller supplies: a reason, a human-readable name, and an optional referenceDocumentUri to tie the adjustment back to a warehouse document, CSV import, or ticket.

Key differences from inventoryBulkAdjustQuantityAtLocation:

• Scope: The old mutation targeted a single location per call; the new one accepts changes for multiple locations in a single request.
• Metadata: inventoryAdjustQuantities supports reason, name, and referenceDocumentUri; these fields do not exist on the deprecated call.
• Response: Instead of returning modified inventoryLevels directly, the new mutation returns a group object ID that you can store for audit and cross-referencing.
• Transactional grouping: Changes are recorded as a group, making it easier to track which changes are associated with a single physical action (for example, a stocktake or correction).

These changes affect how you design logging, error recovery, and reconciliation strategies.

Syntax and example requests

The following examples show the mutation before and after migration. Keep these as canonical references while updating your client code.

Before (inventoryBulkAdjustQuantityAtLocation)

mutation InventoryBulkAdjustQuantitiesAtLocation($inventoryItemAdjustments: [InventoryAdjustItemInput!]!) {
  inventoryBulkAdjustQuantityAtLocation(
    inventoryItemAdjustments: $inventoryItemAdjustments,
    locationId: "gid://shopify/Location/124656943"
  ) {
    inventoryLevels {
      id
    }
  }
}

Variables:

{
  "inventoryItemAdjustments": [
    {
      "inventoryItemId": "gid://shopify/InventoryItem/30322695",
      "availableDelta": -10
    }
  ],
  "locationId": "gid://shopify/Location/123"
}

After (inventoryAdjustQuantities)

mutation inventoryAdjustQuantities($input: InventoryAdjustQuantitiesInput!) {
  inventoryAdjustQuantities(input: $input) {
    inventoryAdjustmentGroup {
      id
    }
    userErrors {
      field
      message
    }
  }
}

Variables:

{
  "input": {
    "reason": "correction",
    "name": "available",
    "referenceDocumentUri": "logistics://some.warehouse/take/2023-01/13",
    "changes": [
      {
        "delta": -10,
        "inventoryItemId": "gid://shopify/InventoryItem/30322695",
        "locationId": "gid://shopify/Location/123"
      }
    ]
  }
}

Use these examples as a starting point and adapt to your client framework.

Step-by-step migration checklist

Follow this checklist to migrate safely from inventoryBulkAdjustQuantityAtLocation to inventoryAdjustQuantities.

1. Inventory of usages
   • Search your codebase for inventoryBulkAdjustQuantityAtLocation and related helper functions.
   • Identify external systems (webhooks, queued jobs, background workers) that call the mutation indirectly.
2. Gather identifiers and metadata requirements
   • Ensure you can resolve inventoryItemId (GID) for product variants. A ProductVariant object has an inventoryItemId field.
   • Confirm how your system currently resolves locationId; you may need to expand to pass different location ids per change now that a single call can include many locations.
3. Update API calls
   • Replace calls to inventoryBulkAdjustQuantityAtLocation with inventoryAdjustQuantities. Create a new payload that includes reason, name, referenceDocumentUri, and changes with delta, inventoryItemId, and locationId.
4. Add metadata and auditing
   • Set reason to a clear string (e.g., "correction", "stocktake", "lost", "transfer"). Use name to indicate which inventory type or adjustment type you’re altering (for example, "available" or a custom label your operations team uses).
   • Populate referenceDocumentUri with a stable pointer to your internal system (example: logistics://warehouseA/take/2026-02-01/shift1).
5. Error handling and retries
   • Implement robust user error handling: inspect userErrors in the mutation response and log or surface them for operators.
   • Build idempotency or duplicate-detection by storing the returned inventoryAdjustmentGroup id and using it to identify retries or replays.
6. Test in staging
   • Run staged scenarios: single-item single-location, multi-item single-location, multi-item multi-location.
   • Test concurrent adjustments to the same inventoryLevel to observe how your reconciliation logic copes with race conditions.
7. Deploy and monitor
   • Roll out changes behind feature flags or deploy gradually.
   • Monitor inventory reconciliation reports and reconcile numbers from your warehouse management or POS systems with Shopify after migration.
8. Remove or deprecate older code paths
   • Once confident, remove the code that still references the deprecated mutation.
   • Communicate the change in internal docs and update any runbooks.

Completing each step reduces the risk of inventory discrepancies or operational hiccups.

How to build the input payload correctly

The InventoryAdjustQuantitiesInput contains fields that control both behavior and traceability. Understanding each field ensures consistent and auditable inventory changes.

• input.reason (string)
  • Purpose: a short label describing why the adjustment occurred.
  • Use cases: "correction", "stocktake", "supplier_return", "damage", "transfer".
  • Best practice: Keep reasons standardized across your operations team. Store a limited set of controlled values in your system.
• input.name (string)
  • Purpose: a human-readable name for the adjustment operation. Some teams use it to indicate the inventory type or the process performing the change.
  • Example: "available", "backroom-audit", "pos-downtime-sync".
• input.referenceDocumentUri (string; optional)
  • Purpose: a machine-resolvable or human-readable pointer to the originating document.
  • Examples: an internal URL to a stocktake spreadsheet, a logistics manifest identifier (logistics://warehouse-A/stocktake/2026/02/01/shift-2), or an external document in your document management system.
• input.changes (array)
  • Each change object:
    • delta (integer): positive to add stock, negative to remove.
    • inventoryItemId (GID): the global id for the inventory item (variant-level).
    • locationId (GID): the location where the inventory will be adjusted.

As you populate the changes array, consider grouping related deltas into the same input to take advantage of the audit grouping.

Resolving inventoryItemId and locationId

GIDs are required by the GraphQL API. Resolve them before calling the mutation.

• inventoryItemId
  • ProductVariant objects contain an inventoryItemId. Query the GraphQL Admin API for product variants and include inventoryItemId when you list or fetch variants.
  • Example query:

    query variants($first: Int!) {
      productVariants(first: $first) {
        edges {
          node {
            id
            sku
            inventoryItem {
              id
            }
          }
        }
      }
    }
    

  • Alternatively, if you have variant IDs in the REST API, map them to inventory item IDs by fetching variant details.
• locationId
  • Use Shopify’s Locations API to list available locations for the shop. Locations are returned as GIDs in GraphQL or as numeric/UUID ids via REST depending on the endpoint.
  • Example GraphQL to list locations:

    query {
      locations(first: 50) {
        edges {
          node {
            id
            name
            address {
              city
            }
          }
        }
      }
    }
    

  • Verify permissions: the app must have the appropriate scope to read locations and modify inventory at the specified locations.

Always validate both GIDs exist for the store before submitting large batches.

Handling partial failures and userErrors

GraphQL mutations can return userErrors. inventoryAdjustQuantities may process some changes while rejecting others. Plan for partial failures:

• Inspect the mutation response for userErrors and for partial success indicators. Log full responses including the inventoryAdjustmentGroup id when present.
• If there are userErrors relating to specific changes (for example, invalid inventoryItemId or invalid locationId), capture which change failed and why. Implement corrective workflows:
  • For invalid IDs: double-check mappings and refresh cached IDs.
  • For permission errors: confirm the app has the required access scopes.
• For transient failures (network, rate limits), retry with exponential backoff. Maintain an audit record of retries keyed by your own correlation id and the returned inventoryAdjustmentGroup id if available.
• For consistent rejection of a change (e.g., negative stock not permitted by a store-level policy), route the problem to business operations rather than repeating the adjustment.

Returning an inventoryAdjustmentGroup id even in partial failure scenarios is useful: it allows you to correlate logs and support tickets with a single reference.

Idempotency and duplicate handling

The inventoryAdjustQuantities mutation does not inherently accept an idempotency key (based on the provided schema). Avoid duplicate adjustments by:

• Persisting the inventoryAdjustmentGroup id returned by successful calls and checking it before retrying.
• Recording a local operation id for any queued job or external trigger and marking it as “completed” once the mutation returns success. Use that local id to block duplicate jobs.
• For asynchronous or parallel processes, use optimistic locking or a centralized job coordinator to ensure only one writer performs the adjustment for a given batch.

If duplicates occur, implement compensation adjustments where necessary (e.g., reverse the duplicate delta) and communicate with operations to reconcile physical inventory.

Concurrency and race conditions

Inventory can be updated concurrently by multiple actors: sales, returns, manual corrections, third-party integrations. These can create race conditions if not managed.

• Prefer batched mutations where possible to reduce the number of write operations.
• When concurrency is expected:
  • Query current inventory levels before applying a correction if the change depends on the current available quantity.
  • For corrective adjustments that must be absolute (set level to X), consider computing delta = desired - current, then apply the delta in a single mutation.
  • Implement business rules that define precedence (e.g., sales adjustments processed before warehouse corrections) or use operational windows (scheduled syncs) to reduce overlapping updates.

InventoryAdjustQuantities is a tool for recording changes. Your reconciliation logic must account for concurrent flows.

Rate limiting and GraphQL cost management

GraphQL Admin API enforces cost-based rate limiting. Each query/mutation has an associated cost reported in the response extensions. Large batches may run into cost limits.

• Monitor the ‘extensions’ object in GraphQL responses to check remaining cost and throttle accordingly.
• Break very large batch operations into smaller chunks (for example, groups of 25–100 changes depending on mutation cost) and apply them sequentially.
• For high-throughput systems, implement a backoff strategy that checks remaining cost before sending the next mutation.
• Consider job queues with rate-limiting workers to pace adjustments and avoid sudden spikes that could be throttled.

Batched operations reduce network overhead and group related changes, but cost management remains essential.

Auditing and reconciliation best practices

Use the metadata returned by inventoryAdjustQuantities to build reliable audit trails.

• Store inventoryAdjustmentGroup id, timestamp, input payload, and the user or system that triggered the change.
• Link the referenceDocumentUri to your internal documents: stocktake spreadsheets, scanned manifests, or third-party receipts.
• Implement nightly or hourly reconciliation jobs that:
  • Query inventory levels from Shopify for a set of SKUs and locations.
  • Compare with your warehouse management system (WMS) or point-of-sale (POS) data.
  • Flag discrepancies greater than a tolerance level for manual review.

A single group id serves as a pivot for support and audit queries across logs, webhooks, and operator records.

Monitoring and alerts

After migrating, keep a close eye on metrics that indicate successful operation:

• Error rate for inventoryAdjustQuantities calls.
• Count of userErrors returned per day and their categories.
• Number of retries and duplicate corrections detected.
• Divergence between Shopify inventory and WMS/POS reported inventory.

Set alerts on abnormal spikes (for instance, if userErrors increase suddenly or the rate of corrections changes dramatically), and route those alerts to the responsible engineering or operations teams.

Sample implementations

Below are pragmatic examples showing how to invoke inventoryAdjustQuantities from popular environments. Replace placeholders with actual shop domain and access token.

Node.js (fetch)

const fetch = require('node-fetch');

async function adjustQuantities(shop, accessToken, input) {
  const url = `https://${shop}/admin/api/unstable/graphql.json`; // or a stable version endpoint
  const query = `
    mutation inventoryAdjustQuantities($input: InventoryAdjustQuantitiesInput!) {
      inventoryAdjustQuantities(input: $input) {
        inventoryAdjustmentGroup {
          id
        }
        userErrors {
          field
          message
        }
      }
    }
  `;

  const body = JSON.stringify({ query, variables: { input }});
  const res = await fetch(url, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-Shopify-Access-Token': accessToken
    },
    body
  });

  const json = await res.json();
  if (json.errors) {
    throw new Error(`GraphQL errors: ${JSON.stringify(json.errors)}`);
  }
  return json.data.inventoryAdjustQuantities;
}

// Example usage:
const input = {
  reason: "correction",
  name: "available",
  referenceDocumentUri: "logistics://warehouseA/stocktake/2026-02-10/shift-1",
  changes: [
    {
      delta: -10,
      inventoryItemId: "gid://shopify/InventoryItem/30322695",
      locationId: "gid://shopify/Location/123"
    }
  ]
};

cURL example

curl -s -X POST "https://{shop}.myshopify.com/admin/api/unstable/graphql.json" \
  -H "Content-Type: application/json" \
  -H "X-Shopify-Access-Token: {access_token}" \
  -d '{
    "query": "mutation inventoryAdjustQuantities($input: InventoryAdjustQuantitiesInput!) { inventoryAdjustQuantities(input: $input) { inventoryAdjustmentGroup { id } userErrors { field message } } }",
    "variables": {
      "input": {
        "reason": "correction",
        "name": "available",
        "referenceDocumentUri": "logistics://warehouseA/stocktake/2026-02-10/shift-1",
        "changes": [
          {
            "delta": -10,
            "inventoryItemId": "gid://shopify/InventoryItem/30322695",
            "locationId": "gid://shopify/Location/123"
          }
        ]
      }
    }
  }'

Ruby (Net::HTTP)

require 'net/http'
require 'json'
uri = URI("https://#{shop}/admin/api/unstable/graphql.json")
req = Net::HTTP::Post.new(uri)
req['Content-Type'] = 'application/json'
req['X-Shopify-Access-Token'] = access_token

query = <<-GRAPHQL
mutation inventoryAdjustQuantities($input: InventoryAdjustQuantitiesInput!) {
  inventoryAdjustQuantities(input: $input) {
    inventoryAdjustmentGroup {
      id
    }
    userErrors {
      field
      message
    }
  }
}
GRAPHQL

payload = {
  query: query,
  variables: {
    input: {
      reason: "correction",
      name: "available",
      referenceDocumentUri: "logistics://warehouseA/stocktake/2026-02-10/shift-1",
      changes: [
        {
          delta: -10,
          inventoryItemId: "gid://shopify/InventoryItem/30322695",
          locationId: "gid://shopify/Location/123"
        }
      ]
    }
  }
}

req.body = payload.to_json
http = Net::HTTP.new(uri.hostname, uri.port)
http.use_ssl = true
res = http.request(req)
puts res.body

Adjust these samples for your preferred language and GraphQL client library.

Real-world migration scenarios

Include concrete examples to highlight common migration patterns and pitfalls.

Scenario 1 — Warehouse stocktake correction

• Context: A warehouse completes a physical stocktake and finds SKU123 actually has 95 units instead of the system’s 105.
• Steps:
  • Query Shopify to fetch the current available count for SKU123 at location A.
  • Compute delta = 95 - current (e.g., -10).
  • Call inventoryAdjustQuantities with reason="stocktake", name="available", referenceDocumentUri pointing to the stocktake report, and a single change with the computed delta.
  • Store returned inventoryAdjustmentGroup id for audit.

Scenario 2 — Multi-location transfer correction

• Context: A transfer between location A and location B was not recorded properly, leaving inconsistent stock.
• Steps:
  • Create two changes in a single inventoryAdjustQuantities call:
    • delta: -X for inventoryItemId at location A.
    • delta: +X for the same inventoryItemId at location B.
  • Use reason="transfer-correction" and referenceDocumentUri linking to the transfer manifest or ticket.
  • Using one call ensures both adjustments are part of one adjustment group for easier reconciliation.

Scenario 3 — POS downtime resync

• Context: POS operated offline, and sales increments need to be applied to Shopify once connectivity is restored.
• Steps:
  • Aggregate offline sales per inventoryItemId and location.
  • For each inventoryItemId/location pair compute a single negative delta equal to the sold quantity.
  • Submit aggregated changes in a single inventoryAdjustQuantities call with reason="pos-offline-sync" and a reference to the POS batch file.

These scenarios show why the ability to batch multiple deltas across locations is operationally useful.

Common migration pitfalls and how to avoid them

• Failing to update ID resolution flows
  • Risk: Calling the mutation with an invalid inventoryItemId or locationId will produce userErrors.
  • Mitigation: Implement ID resolution and refresh cached IDs where necessary.
• Not handling userErrors and partial failures
  • Risk: Some changes may succeed and others fail within a request, causing inconsistent expectations.
  • Mitigation: Inspect mutation responses thoroughly and implement compensating actions or manual escalation.
• Overlooking rate limits when batching
  • Risk: Sending very large batches may exceed GraphQL cost quotas.
  • Mitigation: Chunk large batches and monitor cost in the response extensions.
• Not recording inventoryAdjustmentGroup ids
  • Risk: Duplicate submissions become hard to detect.
  • Mitigation: Persist the returned group id along with source job ids and referenceDocumentUri.
• Assuming the mutation is idempotent
  • Risk: Replaying the same payload could double-apply adjustments.
  • Mitigation: Use local deduplication mechanisms and track operation status outside Shopify.
• Misusing reason and name fields
  • Risk: Free-text fields become noisy and hard to filter in audits.
  • Mitigation: Use a finite controlled vocabulary for reason and name entries and enforce it at the application level.

Address these points before rolling changes to production.

Testing and rollout strategy

Adopt a phased rollout to minimize operational disruption.

1. Unit tests
   • Validate payload construction and parsing of mutation responses.
   • Mock userErrors and error cases.
2. Integration tests in staging
   • Use a staging store to validate the full lifecycle for small batches.
   • Test edge cases: invalid IDs, concurrency with simultaneous sales, and partial change arrays.
3. Canary rollout
   • Deploy to a subset of stores or run the new code for a subset of SKUs and locations.
   • Compare before and after inventory reports for discrepancies. Run reconciliation daily.
4. Full production rollout
   • After canary verification, enable for all stores or all operations.
   • Keep monitoring dashboards and alerts active for the first 24–72 hours.
5. Post-deployment audits
   • Run reconciliation reports for the first week to confirm inventory stability.
   • Review userErrors and operational logs and triage any unexpected activity.

Gradual rollout and thorough testing limit the blast radius of bugs.

Operational considerations for integrations

Third-party systems interacting with Shopify inventory will need adjustments beyond code changes.

• Warehouse Management Systems (WMS)
  • Update WMS connectors to emit referenceDocumentUri and reason when calling Shopify.
  • Use inventoryAdjustmentGroup ids to reconcile WMS transactions with Shopify records.
• Point-of-Sale (POS) systems
  • Ensure POS reconciliations map to inventoryItemId and locationId. Varied location mapping among POS terminals can cause misapplied deltas.
• Accounting systems
  • Stock adjustments often lead to inventory valuation differences. Tag adjustments with reason codes that make accounting reconciliation easier (e.g., "damage", "supplier_return").
• Third-party marketplaces and fulfillment networks
  • Communicate expected timing for inventory adjustments for synchronized listings.

Coordinating changes across integrated systems preserves data integrity.

Logging and observability recommendations

Instrumentation will be the backbone of reliable operations.

• Log inputs and full mutation responses to a secure audit store.
• For each inventory adjustment, log:
  • Initiator (user id or system id)
  • inventoryAdjustmentGroup id
  • referenceDocumentUri
  • payload (changes)
  • response userErrors
• Correlate logs with reconciliation reports and webhooks (if used).
• Create dashboards showing:
  • Successful adjustments per hour/day
  • Trend of userErrors over time
  • Average latency of adjustments
• Set up alerts on:
  • Spike in adjustments or failure rates
  • High number of userErrors for a specific reason code

Observability reduces mean time to detect and repair problems.

When to keep running the old mutation during transition

If your deployment strategy requires a short coexistence period:

• Encapsulate both code paths behind a feature flag.
• For each trigger, run the new mutation and keep the old one for a transitional subset. Verify results match.
• After sufficient verification, flip the flag to remove the legacy path.

Do not rely on coexistence indefinitely; Shopify intends to remove the deprecated mutation.

Frequently encountered userErrors and responses

Below are representative error categories you may encounter and recommended actions:

• Invalid inventoryItemId
  • Action: Refresh variant-to-inventory mappings; confirm product/variant hasn’t been deleted.
• Invalid locationId
  • Action: Re-query locations and ensure the app has permission to access or write to that location.
• Permission/authorization denied
  • Action: Verify the app has the necessary inventory and location scopes. Reauthorize if needed.
• Negative stock policy violation
  • Action: Check store settings and business rules. If policy prevents negative stock, compute an alternate delta or route to manual intervention.
• Rate-limiting or throttling
  • Action: Implement backoff and chunking. Monitor cost extension for throttling signals.

Proper error categorization and remediation steps reduce operational friction.

Best practices checklist (summary)

Use this checklist when migrating and operating inventory adjustments:

• Replace all references to inventoryBulkAdjustQuantityAtLocation with inventoryAdjustQuantities.
• Resolve and validate inventoryItemId and locationId for each change.
• Populate reason, name, and referenceDocumentUri consistently.
• Persist returned inventoryAdjustmentGroup id.
• Implement robust handling of userErrors and partial success responses.
• Manage GraphQL cost and chunk large batches.
• Build idempotency/deduplication safeguards.
• Perform staged rollout and reconciliation testing.
• Instrument logging and monitoring for adjustments and errors.
• Update operational runbooks and notify stakeholders (warehouse, POS, third-party integrators).

Keeping to this checklist reduces the risk of inventory drift and support load.

FAQ

Q: What exactly is being removed? A: Shopify will remove the inventoryBulkAdjustQuantityAtLocation mutation from the Admin GraphQL API. Apps using that mutation must migrate to inventoryAdjustQuantities to continue performing inventory changes.

Q: Does inventoryAdjustQuantities replace all use cases of the old mutation? A: Yes. inventoryAdjustQuantities supports adjustments across multiple items and locations in a consistent, auditable format and includes metadata fields that enhance traceability.

Q: What fields are required in the new mutation? A: The new mutation requires an InventoryAdjustQuantitiesInput, which includes at minimum the changes array (each with delta, inventoryItemId, and locationId). You should also provide reason and name to aid auditing; referenceDocumentUri is optional but recommended for traceability.

Q: How do I obtain inventoryItemId and locationId values? A: Retrieve inventoryItemId from ProductVariant.inventoryItem or equivalent endpoints that expose the inventory item GID. Retrieve locationId via Shopify’s Locations API or the GraphQL locations query. Validate IDs before submitting mutations.

Q: How should I handle partial failures? A: Inspect the mutation response for userErrors and inventoryAdjustmentGroup id. Log detailed info, mark failed changes for manual review or retry with corrections, and avoid blindly retrying the entire payload without deduplication.

Q: Is there an idempotency key for inventoryAdjustQuantities? A: The mutation does not expose a dedicated idempotency key. Create your own client-side deduplication by storing the inventoryAdjustmentGroup id and associating it with the triggering job or transaction id.

Q: Will batching reduce API calls? A: Yes. Grouping multiple changes across items and locations into a single inventoryAdjustQuantities call reduces the total number of API calls and keeps related changes grouped for auditing. Watch GraphQL cost limits and chunk very large batches.

Q: What scope or permissions does my app need? A: The app must have appropriate inventory and location access scopes to read item and location identifiers and to perform inventory adjustments. Confirm scopes and reauthorize if necessary.

Q: What should I use for referenceDocumentUri? A: Use a stable, meaningful pointer to the source document: a URL to a stocktake report, a logistics manifest id (for example, logistics://warehouse-A/transfer/2026-02-01/1234), or an internal ticket id. This makes audits and support queries far easier.

Q: Will old calls continue to work until removal? A: The deprecated mutation may continue to work until Shopify removes it. Do not rely on that; migrate proactively to avoid service disruption.

Q: How can I audit adjustments after the migration? A: Persist the returned inventoryAdjustmentGroup id and the input payload in your logs. Use these ids in support cases and reconciliation tasks. Combine Shopify-level queries with your internal logs to create a complete audit trail.

Q: What if I need help during migration? A: Prepare a migration runbook with contact points: engineering, operations, warehouse supervisors, and any third-party integrators. Use staging stores to validate changes before production rollout. If you need vendor or platform support, provide mutation request/response logs plus the relevant inventoryAdjustmentGroup ids.

---

This migration creates a more consistent and auditable model for inventory changes. Update your code to call inventoryAdjustQuantities, add robust handling for partial failures and backoff for GraphQL cost limits, and use metadata fields to keep inventory actions traceable to operational events. Follow a staged rollout and reconciliation plan to keep stock records aligned and avoid business disruption.