Quality Control API (Returns V2) | Swap Knowledge Base

API Description

The Quality Control (QC) API enables integration with Swap’s QC system to record and update the condition of returned items.

It complements existing CSV and Mintsoft integrations, allowing compatibility with a wider range of warehouse management systems (WMS).

API Logic

When called, the API updates QC information for one or more returned items.

If a SKU does not match an existing order, it is recorded in the Unexpected tab in the RMA list for administrative review.

Authentication

All requests require an API token in the x-api-key header.

How to generate an API key

Go to Returns → Quality Control Settings in the Swap dashboard.
Enable Quality Control.
Click Generate API Key.
Copy the token from the popup (it will not be shown again).

Note: Once generated, the “Generate API Key” button is disabled to prevent duplicates.

Header Example

x-api-key: your_api_token_here

Endpoint

Method: POST

URL:

<https://api-mfdugldntq-nw.a.run.app/v1/external/quality-control/update>

Headers

Key	Value	Required
x-api-key	Your API token	Yes

Request Payload

Field	Type	Required	Description
provider	string	No	ID of the integration provider (provided by Swap)
store_id	string	Yes	Store identifier (provided by Swap)
sku	string	Yes	SKU of the item
condition	string	Yes	Item condition (see valid values below)
return_qty	number	Yes	Quantity returned
shopify_order_name	string	No	Shopify order number
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

Valid Condition Values

Damaged
Missing
No-Value
Pending
Sellable
Wrong-Item
Not Expected
Qty Mismatch

Example Request

Request Method & URL

POST <https://api-mfdugldntq-nw.a.run.app/v1/external/quality-control/update>

Headers

x-api-key: your_api_token_here Content-Type: application/json

Body

{
  "store_id": "your-swap-id",
  "sku": "SKU-001",
  "condition": "sellable",
  "return_qty": 1,
  "shopify_order_name": "ORDER-123",
  "order_date": "2024-03-20T10:30:00Z",
  "receipt_date": "2024-03-25T15:45:00Z",
  "carton_id": "CART-001"
}

cURL

curl -X POST "<https://api-mfdugldntq-nw.a.run.app/v1/external/quality-control/update>" \
  -H "x-api-key: your_api_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "store_id": "your-swap-id",
    "sku": "SKU-001",
    "condition": "sellable",
    "return_qty": 1,
    "shopify_order_name": "ORDER-123",
    "order_date": "2024-03-20T10:30:00Z",
    "receipt_date": "2024-03-25T15:45:00Z",
    "carton_id": "CART-001"
  }'

Business Logic

Unexpected SKUs are logged in the Unexpected tab.
Quantity mismatches are flagged as Qty Mismatch after 48 hours without an update from the 3PL.
Missing items are flagged as Missing after 48 hours without update.
Items remain Pending until resolved.
Orders pass QC only if all items are approved according to mapping logic.

Success Response

{
  "status": 200,
  "reason": "OK",
  "entity": {
    "data": [],
    "messages": [
      {
        "message": "Quality control conditions updated successfully",
        "type": "firestore/quality-control-providers"
      }
    ],
    "meta": {}
  }
}

Error Responses

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