Returns API Overview

The Returns API lets you retrieve returns. You can fetch a single return in full detail — by its unique identifier or by its return reference — or list returns filed by a specific customer (applicant), against a specific order, or against a specific invoice (billing document).

All request/response examples use placeholder values; field names and types match what the API returns.

Base URL

https://<store-url>/public/returns/v1

<store-url> is the base URL issued to your store, per environment (sandbox / production). See Getting Started → Base URL for the full list of hosts. All paths below are relative to it.

Authentication

Every request must be authenticated. You need two credentials on each call:

Header	Value	Purpose
`Authorization`	`Bearer <access_token>`	OAuth 2.0 JWT access token
`Ocp-Apim-Subscription-Key`	`<your-subscription-key>`	Identifies your subscription at the API gateway

The access token must carry the returns:read scope. A token without it is rejected with 403 Forbidden.
Tokens are short-lived (typically 30–60 minutes). Request a new token when the old one expires.
For details on obtaining a token, supported authorities, and the claims involved, see Getting Started → Authentication.

Beyond the scope check, per-return access control applies: you only see returns your account is entitled to (returns sold to an account you own, or with an explicit relationship). Requesting a return you are not entitled to returns 403 Forbidden; in list responses such returns are silently omitted (see Pagination).

Conventions

Format: JSON only (Accept: application/json). Field names are camelCase.
Enums are serialized as strings (e.g. "Approved", "PhysicalProduct"), never as numbers.
Timestamps are ISO 8601 with an explicit UTC offset, e.g. 2026-05-01T09:32:00+02:00.
Nullable fields are present in the payload with a null value when not applicable.
Each response carries an X-Trace-Id header. Quote it when contacting support — it lets us correlate your request with our logs.

Endpoints

Method	Path	Description
`GET`	`/returns/v1/{returnId}`	Retrieve one return in full detail, by its unique identifier
`GET`	`/returns/v1/return-reference/{returnReference}`	Retrieve one return in full detail, by its return reference
`GET`	`/returns/v1/list/applicant/{applicantCustomerId}`	List returns filed by a customer (the applicant)
`GET`	`/returns/v1/list/order/{orderReference}`	List returns filed against a specific original order
`GET`	`/returns/v1/list/invoice/{invoiceReference}`	List returns filed against a specific invoice (billing document)

The three list endpoints return the same full return shape, one per item in returns — there is no separate summary shape, unlike Orders. They differ only in which reference the path value is matched against.

1. Get return by ID

GET /returns/v1/{returnId}

Retrieves a single return by its unique identifier.

Path parameters

Name	Type	Required	Description
`returnId`	string (GUID)	yes	The unique identifier of the return.

Responses

Status	Meaning
`200 OK`	Return found and you are entitled to see it. Body is a return.
`400 Bad Request`	`returnId` was empty.
`401 Unauthorized`	Missing or invalid token.
`403 Forbidden`	Token lacks `returns:read`, or you are not entitled to this return.
`404 Not Found`	No return exists with that id.
`500 Internal Server Error`	Unexpected server error.

Example response (200 OK)

{
  "return": {
    "returnId": "11111111-1111-1111-1111-111111111111",
    "returnReference": "60601368",
    "storeId": "310",
    "reason": "ItemWasDefect",
    "informationToCustomer": null,
    "sourceSystem": "Web",
    "status": "Approved",
    "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": "2004309017",
      "invoiceReference": "9004271739"
    },
    "shippingDetails": {
      "transporterBookingId": "POST-5566778",
      "trackingUrl": "https://tracking.example.com/POST-5566778"
    },
    "returnType": "Return",
    "items": [
      {
        "lineNumber": "10",
        "parentLineNumber": null,
        "itemCategory": "PhysicalProduct",
        "invoiceLineNumber": "10",
        "materialNumber": "1343062",
        "productName": "Wireless Mouse",
        "quantity": 1
      }
    ],
    "createdAtUtc": "2026-09-20T08:15:00+00:00",
    "updatedAtUtc": "2026-09-27T13:42:11+00:00",
    "estimatedProcessingTime": "3-5 business days"
  }
}

2. Get return by return reference

GET /returns/v1/return-reference/{returnReference}

Retrieves a single return by its return reference — an alternative lookup key to returnId, resolving to the exact same return shape.

Path parameters

Name	Type	Required	Description
`returnReference`	string	yes	The return’s return reference.

Responses

Status	Meaning
`200 OK`	Return found and you are entitled to see it. Body is a return.
`400 Bad Request`	`returnReference` was empty.
`401 Unauthorized`	Missing or invalid token.
`403 Forbidden`	Token lacks `returns:read`, or you are not entitled to this return.
`404 Not Found`	No return exists with that return reference.
`500 Internal Server Error`	Unexpected server error.

The example response is identical in shape to Get return by ID above.

3. List returns by applicant customer

GET /returns/v1/list/applicant/{applicantCustomerId}

Lists returns filed by the given customer (the applicant — the party who submitted the return), newest updated first by default.

Path parameters

Name	Type	Required	Description
`applicantCustomerId`	string (GUID)	yes	Customer who filed the returns.

Supports filtering, sorting and paging via query string.

4. List returns by original order

GET /returns/v1/list/order/{orderReference}

Lists returns filed against the given original order, newest updated first by default.

Path parameters

Name	Type	Required	Description
`orderReference`	string	yes	The original order the returns relate to.

Supports filtering, sorting and paging via query string.

5. List returns by invoice

GET /returns/v1/list/invoice/{invoiceReference}

Lists returns filed against the given invoice (billing document), newest updated first by default.

Path parameters

Name	Type	Required	Description
`invoiceReference`	string	yes	The invoice (billing document) the returns relate to.

Supports filtering, sorting and paging via query string.

Responses (all three list endpoints)

Status	Meaning
`200 OK`	Body is a paged list of returns. May be empty.
`400 Bad Request`	A path or query parameter failed validation (see Errors).
`401 Unauthorized`	Missing or invalid token.
`403 Forbidden`	Token lacks `returns:read`.
`500 Internal Server Error`	Unexpected server error.

Example response (200 OK)

{
  "returns": [
    {
      "returnId": "11111111-1111-1111-1111-111111111111",
      "returnReference": "60601368",
      "storeId": "310",
      "reason": "ItemWasDefect",
      "informationToCustomer": null,
      "sourceSystem": "Web",
      "status": "Approved",
      "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": "2004309017",
        "invoiceReference": "9004271739"
      },
      "shippingDetails": null,
      "returnType": "Return",
      "items": [],
      "createdAtUtc": "2026-09-20T08:15:00+00:00",
      "updatedAtUtc": "2026-09-27T13:42:11+00:00",
      "estimatedProcessingTime": null
    }
  ],
  "continuationToken": "eyJwYWdlIjogMn0="
}

Query parameters for list endpoints

All parameters are optional. With none supplied you get the first page, newest updated first.

Parameter	Type	Default	Description
`CreatedFromUtc`	timestamp	(open)	Only returns created at or after this instant. Must not be earlier than 2023-10-14 (no return data exists before then).
`CreatedToUtc`	timestamp	(open)	Only returns created at or before this instant. Must not be earlier than `CreatedFromUtc`.
`UpdatedFromUtc`	timestamp	(open)	Only returns last updated at or after this instant. Must not be earlier than 2023-10-14.
`UpdatedToUtc`	timestamp	(open)	Only returns last updated at or before this instant. Must not be earlier than `UpdatedFromUtc`.
`SortBy`	`CreatedAtUtc` \| `UpdatedAtUtc`	`UpdatedAtUtc`	Field to sort by.
`SortDir`	`Asc` \| `Desc`	`Desc`	Sort direction.
`PageSize`	integer	`20`	Page size, 1–50.
`ContinuationToken`	string	(none)	Opaque token from a previous response, used to fetch the next page.

Query parameter names are matched case-insensitively.

Validation errors (400) are returned when: CreatedFromUtc/UpdatedFromUtc is earlier than 2023-10-14, CreatedFromUtc is later than CreatedToUtc, UpdatedFromUtc is later than UpdatedToUtc, or PageSize is outside 1–50.

Example

GET /returns/v1/list/applicant/8b1e4f2a-3c5d-4a6b-9e7f-1a2b3c4d5e6f?CreatedFromUtc=2026-01-01T00:00:00Z&PageSize=25&SortDir=Asc

Pagination

List endpoints are cursor-based, not page-numbered. Read these rules carefully — they affect correctness:

A response includes a continuationToken when more results may be available, or null when you have reached the end.
To fetch the next page, repeat the same request and pass the token back as the ContinuationToken query parameter.
There is no total count. Do not rely on result counts to decide when to stop.
Per-return access control is applied after paging. Because of this, a page may contain fewer items than PageSize, or even be empty, while still returning a non-null continuationToken. An empty page does not mean you are done.
Keep following continuationToken until it is null. That — and only that — signals the end of the result set.

GET .../list/applicant/{applicantCustomerId}                          → { "returns": [...], "continuationToken": "abc" }
GET .../list/applicant/{applicantCustomerId}?ContinuationToken=abc    → { "returns": [],    "continuationToken": "def" }  // not finished!
GET .../list/applicant/{applicantCustomerId}?ContinuationToken=def    → { "returns": [...], "continuationToken": null  }  // finished

Response models

Return

Returned by get-by-id under the top-level return property, and one per item in returns on the list endpoints — both shapes are identical (no separate summary shape).

Return

Field	Type	Description
`returnId`	string (GUID)	Unique return identifier.
`returnReference`	string	Alternative lookup key — see Get return by return reference.
`storeId`	string	Store the return was filed against.
`reason`	string	Return reason. See note on `reason`.
`informationToCustomer`	string \| null	Free-text information set by returns department and shown to the customer, if any.
`sourceSystem`	string	System the return originated from (e.g. `"Web"`).
`status`	string enum	Current status of the return.
`repairStatus`	string enum	Repair status; `"NA"` when the return isn’t a repair.
`conclusion`	string enum	Conclusion reached, once decided; `"None"` until then.
`parties`	Parties	The customers involved.
`references`	References	Order/invoice references the return relates to.
`shippingDetails`	ShippingDetails \| null	Return shipment tracking details, once available.
`returnType`	string enum	Return type — a plain return or a repair.
`items`	ReturnItem[]	The returned items.
`createdAtUtc`	timestamp	When the return was created.
`updatedAtUtc`	timestamp	When the return was last updated.
`estimatedProcessingTime`	string \| null	Free-text estimate of processing time (e.g. `"3-5 business days"`), if known.

A note on reason
Section titled “A note on reason”

reason is the name of the backend’s return reason (e.g. "ItemWasDefect", "DontWantIt", "WrongItemReceived"). It is not a fixed, documented enum on this API — treat it as an opaque, human-readable label rather than switching on specific values. New reasons may be added on the backend over time without a version change here.

Parties

Field	Type	Description
`soldTo`	string (GUID)	Customer the original order was sold to.
`shipTo`	string (GUID)	Customer/destination the return ships to.
`applicant`	string (GUID) \| null	Customer who filed the return.

References

Field	Type	Description
`orderReference`	string \| null	The original order the return relates to.
`invoiceReference`	string \| null	The invoice (billing document) the return relates to.

ShippingDetails

Field	Type	Description
`transporterBookingId`	string \| null	Carrier booking identifier.
`trackingUrl`	string \| null	URL to track the return shipment.

ReturnItem

Field	Type	Description
`lineNumber`	string	Identifier of the line within the return.
`parentLineNumber`	string \| null	Parent line, for nested/component items.
`itemCategory`	string enum	Item category.
`invoiceLineNumber`	string \| null	The invoice line this return line relates to.
`materialNumber`	string	Material/SKU number.
`productName`	string \| null	Product name.
`quantity`	integer	Quantity returned on the line.

List response wrapper

Field	Type	Description
`returns`	Return[]	The page of returns (possibly empty).
`continuationToken`	string \| null	Cursor for the next page; `null` at the end. See Pagination.

Enumerations

Status values

Value	Meaning
`Unconfirmed`	Return submitted, not yet confirmed.
`AwaitingApproval`	Awaiting a decision.
`Approved`	Return approved.
`Rejected`	Return rejected.
`ApprovedItemNotReceived`	Approved, and item is expected to be shippied back, but has not arrived yet.
`InTransit`	Cuourrier has notified that item is on its way.
`Delivered`	Courrier has notified that item has been delivered to the warehouse/partner.
`ItemReceived`	Item received and scanned in at warehouse
`ReferredToServicePartner`	Handed off to a service partner.
`ReferredToCustomerService`	Handed off to customer service.
`Service`	Being handled as a service case.
`Completed`	Return fully processed.

Repair status values

Only meaningful when returnType is "Repair"; otherwise "NA".

Value	Meaning
`NA`	Not applicable — not a repair.
`Other`	Other/unclassified repair state.
`Created`	Repair case created.
`InTransit`	Item on its way to the repair partner.
`Delivered`	Item delivered to the repair partner.
`Received`	Item received by the repair partner.
`InProgress`	Repair in progress.
`AwaitingCustomer`	Waiting on the customer.
`AwaitingParts`	Waiting on parts.
`Rejected`	Repair rejected.
`Completed`	Repair completed.
`InReturnTransit`	Repaired item on its way back to the customer.

Conclusion values

Value	Meaning
`None`	No conclusion reached yet.
`ReturnedToCustomer`	Item sent back to the customer unchanged.
`Refunded`	Customer refunded.
`ShipToRepair`	Item sent for repair.
`Replaced`	Item replaced.

Return type values

Value	Meaning
`Return`	A standard return.
`Repair`	A repair case.

Return item category values

Value	Meaning
`ServiceOrNonPhysicalProduct`	A service or non-physical product.
`FreeOfCharge`	A free-of-charge item.
`PhysicalProduct`	A physical product.
`KpcAndSalesSetParent`	Parent line of a Komplett PC / sales set bundle.
`SharedPaymentDevice`	A shared payment device.
`ConfiguredItem`	A configured item.
`ConfigurationAssistingItem`	An item assisting a configuration.
`ConfiguredItemInstructions`	Instructions accompanying a configured item.
`Freight`	A freight/shipping line.
`Unknown`	Category not classified.

Example return states

Sample responses for get-by-id and list requests are in the companion example docs:

Return detail examples — single-return responses across statuses, return types and item scenarios.
Return list examples — filtering, sorting and pagination samples across all three list endpoints.

Errors

All errors use the RFC 9457 / RFC 7807 Problem Details JSON format.

Problem Details

Field	Type	Description
`type`	string (URI)	Identifies the error category.
`title`	string	Short, human-readable summary of the category.
`detail`	string	Human-readable explanation specific to this occurrence.
`status`	integer	HTTP status code.
`instance`	string	The request path that produced the error.
`code`	string	Stable machine-readable error code (see table below).
`traceId`	string	Correlation id; also returned in the `X-Trace-Id` header. Quote it to support.

Validation errors (400) include an additional errors array, one entry per invalid field:

{
  "type": "...",
  "title": "Validation Failed",
  "detail": "Some fields have validation errors",
  "status": 400,
  "instance": "/returns/v1/list/applicant/11111111-1111-1111-1111-111111111111",
  "code": "ERR_VALIDATION_0001",
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
  "errors": [
    { "fieldName": "Filter.PageSize", "message": "PageSize must be between 1 and 50." }
  ]
}

Status / code reference

HTTP status	`code`	When it happens
`400 Bad Request`	`ERR_VALIDATION_0001`	A path or query parameter failed validation. See `errors[]`.
`401 Unauthorized`	—	Missing, malformed, or expired token / wrong auth scheme.
`403 Forbidden`	`ERR_ACCESS`	Token lacks `returns:read`, or you are not entitled to the requested return.
`404 Not Found`	`ERR_NOTFOUND`	No return exists with the given id.
`500 Internal Server Error`	`InternalServerError`	Unexpected server error. Retry later; quote the trace id if it persists.

Quick start

# 1. Fetch a page of returns filed by a customer
curl -s "https://<store-url>/public/returns/v1/list/applicant/11111111-1111-1111-1111-111111111111f?PageSize=25" \
  -H "Authorization: Bearer <access_token>" \
  -H "Ocp-Apim-Subscription-Key: <subscription_key>" \
  -H "Accept: application/json"

# 2. Take a returnId from the list and fetch the full return
curl -s "https://<store-url>/public/returns/v1/11111111-1111-1111-1111-111111111111" \
  -H "Authorization: Bearer <access_token>" \
  -H "Ocp-Apim-Subscription-Key: <subscription_key>" \
  -H "Accept: application/json"

# 3. Alternatively, fetch a return by its return reference
curl -s "https://<store-url>/public/returns/v1/return-reference/60000001" \
  -H "Authorization: Bearer <access_token>" \
  -H "Ocp-Apim-Subscription-Key: <subscription_key>" \
  -H "Accept: application/json"

To page through all results, repeat the list call with ContinuationToken from each response until it comes back null.