Skip to content
Komplett LogoKomplett Platform

Returns Get by Id

Return Detail — GET /returns/v1/{returnId}

Section titled “Return Detail — GET /returns/v1/{returnId}”

Unlike Orders, the return detail response carries an explicit status field directly — there is no events timeline to derive it from. repairStatus and conclusion accompany it: repairStatus is only meaningful when returnType is "Repair" (otherwise "NA"), and conclusion stays "None" until a decision has been made.

Get by Return Reference — GET /returns/v1/return-reference/{returnReference}

Section titled “Get by Return Reference — GET /returns/v1/return-reference/{returnReference}”

An alternative lookup key to returnId — identical response shape, identical error shape, just keyed on returnReference instead. Use whichever identifier you have on hand; both resolve to the same return. All the lifecycle and item examples below apply equally whichever endpoint you used to reach them.

400 — Validation Error (return reference)

Section titled “400 — Validation Error (return reference)”

Returned when the request is malformed (e.g. empty or whitespace-only returnReference).

{
  "errors": [
    { "fieldName": "ReturnReference", "message": "ReturnReference cannot be null or empty." }
  ],
  "code": "ERR_VALIDATION_0001",
  "status": 400
}

The 401, 403, 404 and 500 responses are identical in shape to the equivalent get-by-ID errors documented further down this page.

Return Lifecycle Examples

Section titled “Return Lifecycle Examples”

Awaiting Approval

Section titled “Awaiting Approval”

Return just filed. No decision made yet.

Response — Awaiting approval 
{
  "return": {
    "returnId": "11111111-1111-1111-1111-111111111111",
    "returnReference": "60000001",
    "storeId": "310",
    "reason": "DontWantIt",
    "informationToCustomer": null,
    "sourceSystem": "Web",
    "status": "AwaitingApproval",
    "repairStatus": "NA",
    "conclusion": "None",
    "parties": {
      "soldTo": "11111111-1111-1111-1111-111111111111",
      "shipTo": "11111111-1111-1111-1111-111111111111",
      "applicant": "11111111-1111-1111-1111-111111111111"
    },
    "references": {
      "orderReference": "2000000001",
      "invoiceReference": "9000000001"
    },
    "shippingDetails": null,
    "returnType": "Return",
    "items": [
      {
        "lineNumber": "10",
        "parentLineNumber": null,
        "itemCategory": "PhysicalProduct",
        "invoiceLineNumber": "10",
        "materialNumber": "1234567",
        "productName": "Logitech MX Keys S Trådløst Tastatur",
        "quantity": 1
      }
    ],
    "createdAtUtc": "2026-09-20T08:15:00+00:00",
    "updatedAtUtc": "2026-09-20T08:15:00+00:00",
    "estimatedProcessingTime": null
  }
}

Initial state:

  • status is AwaitingApproval, conclusion is None
  • shippingDetails is null — nothing has shipped yet
  • createdAtUtc equals updatedAtUtc

Approved — Refunded

Section titled “Approved — Refunded”

Return approved, item received, and the customer refunded.

Response — Approved and refunded 
{
  "return": {
    "returnId": "11111111-1111-1111-1111-111111111111",
    "returnReference": "60000001",
    "storeId": "310",
    "reason": "DontWantIt",
    "informationToCustomer": null,
    "sourceSystem": "Web",
    "status": "Completed",
    "repairStatus": "NA",
    "conclusion": "Refunded",
    "parties": {
      "soldTo": "11111111-1111-1111-1111-111111111111",
      "shipTo": "11111111-1111-1111-1111-111111111111",
      "applicant": "11111111-1111-1111-1111-111111111111"
    },
    "references": {
      "orderReference": "2000000001",
      "invoiceReference": "9000000001"
    },
    "shippingDetails": {
      "transporterBookingId": "POST-5566778",
      "trackingUrl": "https://tracking.example.com/POST-5566778"
    },
    "returnType": "Return",
    "items": [
      {
        "lineNumber": "10",
        "parentLineNumber": null,
        "itemCategory": "PhysicalProduct",
        "invoiceLineNumber": "10",
        "materialNumber": "1234567",
        "productName": "Logitech MX Keys S Trådløst Tastatur",
        "quantity": 1
      }
    ],
    "createdAtUtc": "2026-09-20T08:15:00+00:00",
    "updatedAtUtc": "2026-09-27T13:42:11+00:00",
    "estimatedProcessingTime": null
  }
}

Changes from Awaiting Approval:

  • status moved to Completed, conclusion to Refunded
  • shippingDetails now populated with the return shipment’s tracking information
  • updatedAtUtc advanced past createdAtUtc

Rejected

Section titled “Rejected”

Return reviewed and rejected — no refund or replacement issued.

Response — Rejected 
{
  "return": {
    "returnId": "11111111-1111-1111-1111-111111111111",
    "returnReference": "60000001",
    "storeId": "310",
    "reason": "FoundCheaperProduct",
    "informationToCustomer": "Item shows signs of use outside the return window and does not qualify for return.",
    "sourceSystem": "Web",
    "status": "Rejected",
    "repairStatus": "NA",
    "conclusion": "None",
    "parties": {
      "soldTo": "11111111-1111-1111-1111-111111111111",
      "shipTo": "11111111-1111-1111-1111-111111111111",
      "applicant": "11111111-1111-1111-1111-111111111111"
    },
    "references": {
      "orderReference": "2000000001",
      "invoiceReference": "9000000001"
    },
    "shippingDetails": null,
    "returnType": "Return",
    "items": [
      {
        "lineNumber": "10",
        "parentLineNumber": null,
        "itemCategory": "PhysicalProduct",
        "invoiceLineNumber": "10",
        "materialNumber": "1234567",
        "productName": "Logitech G700s Trådløs Gaming Mus",
        "quantity": 1
      }
    ],
    "createdAtUtc": "2026-09-18T10:02:00+00:00",
    "updatedAtUtc": "2026-09-19T09:11:00+00:00",
    "estimatedProcessingTime": null
  }
}

Key points:

  • status is Rejected; conclusion stays None — rejection is not a conclusion outcome
  • informationToCustomer carries the reason shown to the customer for a rejection

Repair — In Progress

Section titled “Repair — In Progress”

A repair case, distinct from a standard return: returnType is "Repair" and repairStatus tracks the repair’s own lifecycle independently of status.

Response — Repair in progress 
{
  "return": {
    "returnId": "11111111-1111-1111-1111-111111111111",
    "returnReference": "60000001",
    "storeId": "310",
    "reason": "ItemWasDefect",
    "informationToCustomer": null,
    "sourceSystem": "Web",
    "status": "Approved",
    "repairStatus": "InProgress",
    "conclusion": "None",
    "parties": {
      "soldTo": "11111111-1111-1111-1111-111111111111",
      "shipTo": "11111111-1111-1111-1111-111111111111",
      "applicant": "11111111-1111-1111-1111-111111111111"
    },
    "references": {
      "orderReference": "2000000001",
      "invoiceReference": "9000000001"
    },
    "shippingDetails": {
      "transporterBookingId": "POST-5566779",
      "trackingUrl": "https://tracking.example.com/POST-5566779"
    },
    "returnType": "Repair",
    "items": [
      {
        "lineNumber": "10",
        "parentLineNumber": null,
        "itemCategory": "PhysicalProduct",
        "invoiceLineNumber": "10",
        "materialNumber": "1234567",
        "productName": "KS iPhone 14 128GB Midnight",
        "quantity": 1
      }
    ],
    "createdAtUtc": "2026-09-10T07:30:00+00:00",
    "updatedAtUtc": "2026-09-25T12:00:00+00:00",
    "estimatedProcessingTime": "5-10 business days"
  }
}

Key points:

  • returnType is Repair; repairStatus (InProgress) is the meaningful lifecycle field here, not conclusion
  • Once the repair completes, conclusion moves to ShipToRepair or Replaced depending on outcome, and repairStatus moves to Completed

Item Scenarios

Section titled “Item Scenarios”

Multiple Items on One Return

Section titled “Multiple Items on One Return”

A return can cover more than one line from the original order.

Response — Two items 
{
  "return": {
    "returnId": "11111111-1111-1111-1111-111111111111",
    "returnReference": "60000001",
    "storeId": "310",
    "reason": "WrongItemReceived",
    "informationToCustomer": null,
    "sourceSystem": "Web",
    "status": "ItemReceived",
    "repairStatus": "NA",
    "conclusion": "None",
    "parties": {
      "soldTo": "11111111-1111-1111-1111-111111111111",
      "shipTo": "11111111-1111-1111-1111-111111111111",
      "applicant": "11111111-1111-1111-1111-111111111111"
    },
    "references": {
      "orderReference": "2000000001",
      "invoiceReference": "9000000001"
    },
    "shippingDetails": {
      "transporterBookingId": "POST-5566780",
      "trackingUrl": "https://tracking.example.com/POST-5566780"
    },
    "returnType": "Return",
    "items": [
      {
        "lineNumber": "10",
        "parentLineNumber": null,
        "itemCategory": "PhysicalProduct",
        "invoiceLineNumber": "10",
        "materialNumber": "1234567",
        "productName": "Logitech MX Keys S Trådløst Tastatur",
        "quantity": 1
      },
      {
        "lineNumber": "20",
        "parentLineNumber": null,
        "itemCategory": "PhysicalProduct",
        "invoiceLineNumber": "20",
        "materialNumber": "1234567",
        "productName": "Logitech G700s Trådløs Gaming Mus",
        "quantity": 1
      }
    ],
    "createdAtUtc": "2026-09-22T11:00:00+00:00",
    "updatedAtUtc": "2026-09-26T09:40:00+00:00",
    "estimatedProcessingTime": null
  }
}

Key points:

  • items[] lists each returned line independently, each with its own lineNumber, materialNumber and quantity
  • status applies to the return as a whole, not per item

Error Responses — GET /returns/v1/{returnId}

Section titled “Error Responses — GET /returns/v1/{returnId}”

All errors share the same envelope shape. The code field identifies the error type.

400 — Validation Error

Section titled “400 — Validation Error”

Returned when the request is malformed (e.g. empty or whitespace-only returnId).

{
  "errors": [
    { "fieldName": "Id", "message": "ReturnId cannot be null or empty." }
  ],
  "code": "ERR_VALIDATION_0001",
  "traceId": "TRACE000000000001:00000001",
  "type": "https://<store-url>/swagger#Validation",
  "title": "Validation Failed",
  "status": 400,
  "detail": "Some fields have validation errors",
  "instance": "/returns/v1/%20",
  "extensions": {}
}

The errors[] array lists each invalid field with a human-readable message.

401 — Unauthorized

Section titled “401 — Unauthorized”

No response body. The request is missing or has an invalid Authorization header.

403 — Forbidden (no scope)

Section titled “403 — Forbidden (no scope)”

No response body. The token is valid but does not include the returns:read scope.

403 — Access Denied

Section titled “403 — Access Denied”

Returned when the caller’s token is valid and scoped, but the return belongs to a different account.

{
  "code": "ERR_ACCESS",
  "traceId": "TRACE000000000002:00000001",
  "type": "https://<store-url>/swagger#AccessError",
  "title": "Access Denied",
  "status": 403,
  "detail": "You do not have access to this return.",
  "instance": "/returns/v1/11111111-1111-1111-1111-111111111111",
  "extensions": {}
}

404 — Not Found

Section titled “404 — Not Found”

Returned when the returnId does not exist.

{
  "code": "ERR_NOTFOUND",
  "traceId": "TRACE000000000003:00000001",
  "type": "https://<store-url>/swagger#NotFound",
  "title": "Not Found",
  "status": 404,
  "detail": "Return not found.",
  "instance": "/returns/v1/non-existing-id",
  "extensions": {}
}