ParcelPilot
Help

Shopify Stock Mismatch and Failed Stock Updates

Use this guide when Shopify stock and Parcel Pilot stock do not agree, or when a Shopify stock sync/update fails.

Start with the right question

There are two different stock workflows:

  1. Parcel Pilot pushes stock to Shopify
  2. Parcel Pilot pulls Shopify stock into Parcel Pilot

Troubleshooting is faster if you identify the direction first.

Use this guide when the question is:

  • Why is Shopify stock wrong?
  • Why did a Shopify inventory update fail?
  • Why did Shopify inventory update fail with 404?
  • Why did Shopify stock sync skip this SKU or location?

Parcel Pilot pushes stock to Shopify

This is the normal flow when Parcel Pilot is the stock master.

Current requirements:

  • settings.stock_sync_enabled must be enabled on the Shopify integration
  • settings.stock_master must be parcel_pilot
  • the client must not be in Suspended - monitoring only mode for outbound stock publishing
  • the local item must map to the correct Shopify inventory identity
  • the Shopify location used for the update must still be valid

Common triggers include:

  • posting a receipt with Push stock to ecommerce enabled
  • stock changes published by the inventory workflow
  • manual Push Inventory actions on the integration or item surfaces

Shopify pushes or Parcel Pilot pulls stock from Shopify

This is the sync direction used when Shopify is the stock master.

Current requirements:

  • settings.stock_sync_enabled must be enabled
  • the integration must be configured so Shopify is the stock master for pull-in workflows
  • Parcel Pilot must be able to resolve a target warehouse/location for imported stock
  • Parcel Pilot must be able to map Shopify inventory items back to local SKUs/items

First checks

Before deeper troubleshooting, confirm:

  1. the correct Shopify integration is enabled for the client
  2. the store domain and access token are valid
  3. stock sync is enabled for that integration
  4. the expected stock-master direction is configured
  5. the SKU exists exactly as expected on both sides

If Shopify stock is wrong after a Parcel Pilot stock change

Check these in order.

1. Is stock sync enabled?

If settings.stock_sync_enabled is off, Parcel Pilot will skip normal stock publishing.

2. Is Parcel Pilot actually the stock master?

If settings.stock_master is set to ecommerce, Parcel Pilot will not treat normal local stock changes as authoritative push events unless a force path is used.

3. Is the client suspended for monitoring only?

If the client is in Suspended - monitoring only, Parcel Pilot keeps the Shopify integration connected for inbound observation and diagnostics, but it skips outbound stock pushes.

4. Did the local workflow publish stock?

Current normal examples:

  • Post Receipt can queue stock publication when Push stock to ecommerce stays enabled
  • stock-transfer and other inventory workflows can also publish stock changes

If a receipt was posted with stock push disabled, the local stock may be correct while Shopify remains unchanged.

5. Can Parcel Pilot resolve the Shopify inventory identity?

Stock push depends on the SKU resolving to the correct Shopify inventory item.

If the mapping is stale or incomplete, Parcel Pilot can fail to update Shopify even though the local item exists.

Use Check SKU on the Shopify integration when you need to inspect one upstream SKU and confirm the exact product/variant identity.

If Parcel Pilot stock is wrong after a Shopify pull

Check these in order.

1. Can Parcel Pilot read Shopify locations?

If Shopify does not grant read_locations, location discovery can fail.

Current fallback behavior:

  • if a specific shopify_location_id is configured, Parcel Pilot can fall back to that configured location
  • otherwise the sync can fail with a message that no Shopify locations are available

Recommended fix:

  1. approve read_locations
  2. re-authorize or reinstall the Shopify app if needed

2. Does the integration point at the right Shopify location?

If the wrong Shopify location is selected, the quantities can be correct for Shopify but wrong for the warehouse you expected Parcel Pilot to mirror.

Check:

  • the integration's shopify_location_id
  • the warehouse/location Parcel Pilot uses to store pulled stock

3. Does Parcel Pilot have a warehouse/location to receive synced stock?

Shopify pull-in needs a valid local warehouse and location.

If Parcel Pilot cannot resolve one, the pull fails with a warehouse/location setup error.

Current local destination rules:

  • Parcel Pilot reads from the configured Shopify shopify_location_id when one is set.
  • Imported physical stock is written into the client's default eligible ParcelPilot warehouse.
  • If the integration has an explicit settings.default_warehouse_id and that warehouse is still eligible for the client, Parcel Pilot uses it as an override.
  • Inside the resolved warehouse, Parcel Pilot requires an explicit default_location_id.
  • Client default inbound or returns locations are not used for Shopify inventory pull-in.

If the client has no default eligible warehouse, or the resolved warehouse has no valid Default Location, Shopify pull-in fails until that local configuration is fixed.

4. Can Shopify inventory items be mapped back to local Items?

During pull-in, Parcel Pilot expects Shopify inventory items to resolve to SKUs and then to local Items.

Common problems:

  • the Shopify inventory item has no SKU
  • the SKU exists in Shopify but not in Parcel Pilot Items
  • the SKU exists, but the wrong client or tenant owns the local item

When this happens, Parcel Pilot skips those rows instead of guessing.

Common failure patterns

read_locations permission denied

What it means:

  • Shopify refused location discovery

What to do:

  1. approve read_locations
  2. reconnect if Shopify requires re-authorization
  3. if needed, set a specific shopify_location_id as a temporary fallback

No Shopify locations available

What it means:

  • Parcel Pilot could not discover usable Shopify locations, and it did not have a valid configured fallback

What to do:

  1. check location scope approval
  2. check the configured shopify_location_id
  3. confirm the shop still has that location

SKU not found

What it means:

  • the stock workflow could not resolve the SKU into the Shopify inventory identity it needed for the update

What to do:

  1. confirm the SKU spelling and case-insensitive exact match expectations
  2. use Check SKU to verify the upstream product/variant
  3. import or refresh the item mapping if needed

Inventory item has no SKU

What it means:

  • Shopify returned an inventory item that Parcel Pilot cannot map back to a local Item

What to do:

  1. add/fix the SKU in Shopify
  2. confirm the local Item exists under the same client

Shopify inventory update failed with 404

What it usually means:

  • the update targeted a Shopify identity or location that Shopify no longer recognizes for that integration

Check:

  1. the integration is pointed at the correct shop
  2. the configured shopify_location_id still exists
  3. the SKU still resolves to the same Shopify inventory item/variant
  4. the item was not deleted and recreated upstream, leaving a stale mapping behind

Safe next action:

  • re-check the SKU identity with Check SKU and refresh/re-import the mapping before retrying the stock update

Rate limiting or temporary transport failures

Current Shopify transport paths already retry some failures, but repeated 429 or similar transport errors can still leave stock temporarily out of sync.

In that case:

  1. confirm the underlying SKU/location mapping is correct
  2. retry after the provider limit clears
  3. use the manual stock push/sync action again once the integration is healthy

Fast diagnosis by symptom

"Parcel Pilot stock is correct, Shopify is wrong"

Usually check:

  • stock_sync_enabled
  • stock_master = parcel_pilot
  • receipt/inventory workflow actually published stock
  • SKU/inventory-item mapping

"Shopify stock is correct, Parcel Pilot is wrong"

Usually check:

  • read_locations
  • shopify_location_id
  • local warehouse/location setup
  • SKU exists in Parcel Pilot Items

"One SKU is wrong, others are fine"

Usually check:

  • exact SKU identity
  • whether the variant was recreated upstream
  • whether the local item mapping is stale

Related guides

Selective natural-language aliases

  • why is shopify stock wrong
  • shopify stock mismatch
  • shopify inventory update failed
  • shopify inventory update failed with 404
  • read locations denied
  • shopify location id
  • check sku