Quality Control API (latest version) (Returns V2)

API Description

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

This version introduces support for identifying items using the Shopify line item ID in addition to SKU. This ensures accurate QC updates when multiple variants share the same SKU.

The API 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 both sku and shopify_line_item_id are provided, the shopify_line_item_id will take priority.

If only sku is provided, behaviour remains the same as before.

If a SKU or line item ID does not match an existing order, the item 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-gateway.swap-os.com/returns-api/v1/external/quality-control/update

For testing purposes, please use https://sandbox-apigw.swap-os.com/returns-api/v1/external/quality-control/update instead.

Headers

Key	Value	Required
x-api-key	Your API token	Yes
Content-Type	application/json	yes

Request Payload

Field	Type	Required	Description
provider	string	no	ID of the integration provider. If required, can be provided by swap
store_id	string	Yes	Store identifier (provided by Swap).
sku	string	No	SKU of the item. used for identifying the item for the Quality control status. Optional if shopify_line_item_id is provided.
shopify_line_item_id	string Please use this format: "gid://shopify/LineItem/{{}}"	No	Shopify line item ID. If provided, this will be prioritised over sku.
condition	string	Yes	Item conditions can send any condition. The conditions need to be mapped in swap dashboard in order to affect the QC status in the RMA
return_qty	number	Yes	Quantity returned.
shopify_order_name	string	No	Shopify order number.
order_date	date	No	Date the order was placed (ISO 8601).
receipt_date	date	No	Date the item was received (ISO 8601).
carton_id	string	No	Carton ID for warehouse tracking.

Example Request (using SKU)

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

Headers

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

Body

{
  "provider": "mintsoft",
  "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"
}

Example Request (using Shopify line item ID)

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

Headers

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

Body

{
  "provider": "mintsoft",
  "store_id": "your-swap-id",
  "shopify_order_id": "12345",
  "shopify_order_name": "ORDER-456",
  "shopify_line_item_id": "gid://shopify/LineItem/137272797908",
  "condition": "damaged",
  "return_qty": 1
}

Business Logic

Unexpected items 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.
If the RMA is in a Needs Review state, QC updates will not process, and an error message will explain why.

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": "Authorization Error: User does not have access to the store"
  }
}

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 or Line Item Not Found

{
  "entity": {
    "data": [
      {
        "orderNumber": "#1651",
        "qcCondition": "Bad",
        "quantity": 1,
        "shopify_line_item_id": "gid://shopify/LineItem/999999",
        "success": false,
        "errorMessage": "No returns found by item ID for order"
      }
    ]
  }
}

RMA in Needs Review

{
  "entity": {
    "data": [
      {
        "orderNumber": "#1651",
        "qcCondition": "Good",
        "quantity": 1,
        "sku": "111",
        "success": false,
        "errorMessage": "QC status update failed: RMA is in needs review and cannot be automatically processed"
      }
    ]
  }
}

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