Shopify quality_control: Keep returns unavailable until inspection

What quality_control means

Shopify manages inventory in named states. available represents sellable quantity. quality_control keeps a quantity outside sellable availability while it is being inspected. damaged is intended for stock classified as damaged.

The distinction from on_hand matters: Shopify includes quality_control in total physically present inventory. A return that is still in transit therefore needs a separate receipt record. quality_control prevents selling, but it does not replace parcel tracking or physical inspection.

Why exact state moves are safer

An absolute inventory correction can overwrite sales, transfers, or other changes that happened in the meantime. A quarantine should instead move the evidenced quantity between states: the exact amount leaves available and enters quality_control.

Shopify's inventoryMoveQuantities mutation supports comparison values for the source state. If the previously read value is stale, the operation can stop and become a review case instead of forcing a new quantity.

A controlled lifecycle for returned stock

A reliable workflow tracks each affected variant and location independently. This keeps partial returns and multi-location inventory traceable.

• Protect: available → quality_control.
• Release as sellable: quality_control → available.
• Classify as damaged: quality_control → damaged.
• Uncertain case: no move and human review.

Prevent duplicate processing

Shopify webhooks can be delivered more than once. Every logical inventory action therefore needs a stable idempotency key and a local audit record. A previously completed case must not trigger a second move when an event is repeated.

Return Quarantine combines these rules with a safe Monitor mode. New installations observe without inventory mutations, and merchants deliberately enable Protect later.