Note: This feature is currently in beta. Documentation and behaviour may change prior to full release.
The Quality Control API allows seamless integration with Swap’s Quality Control (QC) system. It complements existing Mintsoft and CSV integrations, enabling wider compatibility with third-party WMS platforms.
Enabling the Quality Control API
Navigate to Quality Control Settings.
Enable Quality Control.
Click Generate API Key. This redirects to the Integrations page and shows a popup with your API key.
Copy the key. The Quality Control API is now active for your store.
Note: Once generated, the “Generate API Key” button is disabled to prevent duplicates.
Unexpected Returns
API calls containing a SKU without a corresponding order number will be automatically categorised in the "unexpected" tab within the RMA list. This section provides visibility of all unexpected items received.
Within this tab, you have the ability to either delete the entry or close the request as needed. This functionality is designed specifically for administrative management purposes and does not affect the workflow.
Endpoint
POST /stores/:swapId/quality-control/update
Headers
Key | Value |
X-API-Key | <your_api_key> |
Request Payload
{ "store_id": "your-swap-id", "sku": "SKU-001", "condition": "sellable", "return_qty": 1, "shopify_order_name": "ORDER-123", // optional "order_date": "2024-03-20T10:30:00Z", // optional "receipt_date": "2024-03-25T15:45:00Z", // optional "carton_id": "CART-001" // optional }
Parameters
Field | Type | Required | Description |
provider | string | Yes | ID of the integration provider (provided by SWAP) |
store_id | string | Yes | Store identifier (provided by SWAP) |
shopify_order_name | string | No | Shopify order number |
sku | string | Yes | SKU of the item |
condition | string | Yes | Item condition (see below) |
return_qty | number | Yes | Quantity returned |
order_date | date | No | Date the order was placed |
receipt_date | date | No | Date the item was received |
carton_id | string | No | Carton ID (for warehouse tracking) |
Condition Values
Valid values for condition include:
Damaged
Missing
No-Value
Pending
Sellable
Wrong-Item
Not Expected
Qty Mismatch
Business Logic
Unexpected SKUs are logged in a separate tab.
Quantity mismatches are flagged as Qty Mismatch after 48 hours without update from 3PL.
Missing items are flagged as Missing after 48 hours with no update.
While pending, the status is Pending.
Orders pass Quality Control only if all items are approved according to mapping logic.
Responses
Success
{ "status": 200, "reason": "OK", "entity": { "data": [], "messages": [ { "message": "Quality control conditions updated successfully", "type": "firestore/quality-control-providers" } ], "meta": {} } }Errors
Invalid API Key
{ "status": 401, "reason": "UNAUTHORIZED", "error": { "message": "Error: Invalid API key" } }Store Access Denied
{ "status": 401, "reason": "UNAUTHORIZED", "error": { "message": "Authorization Error: User does not have access to the store" } }Invalid Condition
{ "entity": { "data": [ { "orderNumber": "#1651", "qcCondition": "dsad", "quantity": 1, "sku": "111", "success": false, "errorMessage": "Error provider condition with name: dsad not found" } ] } }SKU Not Found
{ "entity": { "data": [ { "orderNumber": "#1651", "qcCondition": "Bad", "quantity": 1, "sku": "1121", "success": false, "errorMessage": "No returns found by item SKU:1121 for order ID" } ] } }Order Not Found
{ "entity": { "data": [ { "orderNumber": "#16512", "qcCondition": "Bad", "quantity": 1, "sku": "111", "success": false, "errorMessage": "Error: Order not found." } ] } }Quantity Mismatch
{ "entity": { "data": [ { "orderNumber": "#1651", "qcCondition": "Bad", "quantity": 2, "sku": "111", "comment": "Product quantity in the return is less than expected for this SKU", "success": true } ] } }
HTTP Status Codes
Code | Description |
200 | Success |
400 | Bad Request |
401 | Authentication Error |
500 | Server Error |