Quality Control API (Returns V2)

This article covers what the Quality Control API does, how to authenticate, and how to read its responses. For endpoints, request and response schemas, and worked examples, see the Quality Control API documentation.

The Quality Control (QC) API lets your warehouse or 3PL send item inspection results to Swap as items are scanned, without a provider integration or a CSV upload. Swap maps each condition you send to your configured QC rules and updates the return accordingly.

A QC provider must be configured for your store. Requests for a store with no provider set up return 404.

Each result has to identify both the item and the order it belongs to.

For the item, send sku, shopify_line_item_id, or both. Where both are present, shopify_line_item_id wins — useful when several variants share a SKU.

For the order, send shopify_order_id, shopify_order_name, or both. There's no priority between the two; Swap uses whichever it has. Omitting both returns 400.

If the SKU or line item ID doesn't match anything on the return, Swap records the item as an unexpected item against the order rather than discarding it. See Understanding quality control.

The condition value you send is your provider's own name for that condition, not one of Swap's. It has to match a condition configured for your store's QC provider, or the item is rejected with provider condition with name: <value> not found. Set your conditions up first — see Condition mapping in Understanding quality control.

A 200 response does not mean every item was updated. The API returns 200 for any request it receives successfully, then reports the outcome per item. Check the success field on each item in entity.data, and read errorMessage where success is false.

Items commonly fail while the request still returns 200 because:

Sending a return_qty higher than the quantity on the return behaves differently: Swap processes what it can, creates an unexpected item for the remainder, and returns success: true with a comment explaining the mismatch.

Send your API key in the X-API-Key header. The store is identified by store_id in the request body, not by a query parameter.

A 401 means the key is missing or invalid, or that it doesn't have access to the store in store_id.

One key covers Swap's Returns APIs, so if you already have a key for another of them — the RMA API, for example — use that rather than creating a second.

Your current key is shown, masked, in the API secret key field, with the date it was last updated beneath it.

Rotating deactivates the old key immediately. Update your integration with the new key before you rotate, or requests will start failing.