Quality Control API

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

1. Navigate to Quality Control Settings.
2. Enable Quality Control.
3. Click Generate API Key. This redirects to the Integrations page and shows a popup with your API key.
4. 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

Example: https://api-mfdugldntq-nw.a.run.app/v1/external/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