Returns ListBy

List Endpoints

Three endpoints return a paginated list of returns. They share the same query parameters, response shape, sorting, and paging — they differ only in which reference the path value is matched against.

Endpoint	Returns
`GET /returns/v1/list/applicant/{applicantCustomerId}`	Returns filed by the given customer (the applicant)
`GET /returns/v1/list/order/{orderReference}`	Returns filed against the given original order
`GET /returns/v1/list/invoice/{invoiceReference}`	Returns filed against the given invoice (billing document)

Unlike Orders, list endpoints return the same full Return shape as get-by-id — there is no separate summary shape.

Paging: a page may contain fewer than PageSize returns — including none — yet that does not mean there are no further results. Treat the presence of a continuationToken as the signal that more pages exist, and keep following it until it is null.

Response Model

Response — paginated list of returns

{
  "returns": [
    {
      "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": null,
      "returnType": "Return",
      "items": [],
      "createdAtUtc": "2026-09-20T08:15:00+00:00",
      "updatedAtUtc": "2026-09-27T13:42:11+00:00",
      "estimatedProcessingTime": null
    }
  ],
  "continuationToken": "W3sidG9rZW4i..."
}

Field	Notes
`status`	Explicit string — see status values
`parties.applicant`	The customer who filed the return; matches the path GUID on the applicant list endpoint
`references`	The order/invoice the return relates to; matches the path value on the order/invoice list endpoints
`continuationToken`	Pagination cursor — `null` on the last page

Filtering

The same filter parameters apply to all three endpoints.

Parameter	Type	Notes
`CreatedFromUtc`	timestamp	Earliest `createdAtUtc` to include. Minimum: `2023-10-14`
`CreatedToUtc`	timestamp	Latest `createdAtUtc` to include
`UpdatedFromUtc`	timestamp	Earliest `updatedAtUtc` to include. Minimum: `2023-10-14`
`UpdatedToUtc`	timestamp	Latest `updatedAtUtc` to include

There is no status filter parameter — filter the returned list client-side on status if needed.

Validation rules:

CreatedFromUtc/UpdatedFromUtc cannot be earlier than 2023-10-14 → 400
CreatedFromUtc cannot be later than CreatedToUtc → 400
UpdatedFromUtc cannot be later than UpdatedToUtc → 400

Sorting

Parameter	Values	Default
`SortBy`	`CreatedAtUtc`, `UpdatedAtUtc`	`UpdatedAtUtc`
`SortDir`	`Asc`, `Desc`	`Desc`

SortDir=Asc returns the oldest (by SortBy) returns first.

Pagination

Parameter	Valid range	Default
`PageSize`	1–50	`20`

PageSize=0 or PageSize=51 → 400 with "PageSize must be between 1 and 50."
Pass the continuationToken value from the previous response as ContinuationToken in the next request to fetch the next page
continuationToken: null in the response means this is the last page
A page may contain fewer than PageSize returns (even none) and still have a continuationToken — rely on the token, not the number of records returned, to decide whether to fetch more

Example — first page:

GET /returns/v1/list/applicant/{applicantCustomerId}?PageSize=10&CreatedFromUtc=2026-09-01T00:00:00Z

Response — first page

{
  "returns": [ ... ],
  "continuationToken": "W3sidG9rZW4i..."
}

Example — next page using the token:

GET /returns/v1/list/applicant/{applicantCustomerId}?PageSize=10&CreatedFromUtc=2026-09-01T00:00:00Z&ContinuationToken=W3sidG9rZW4i...

Response — final page

{
  "returns": [ ... ],
  "continuationToken": null
}

continuationToken: null confirms this is the final page.

Sample Dataset

The examples below reference the same set of returns, all filed by Customer A (11111111-1111-1111-1111-111111111111) against three different orders. The date-range and sort examples are issued against GET /list/applicant/11111111-…; the same parameters behave identically on list/order and list/invoice. The final section contrasts the three endpoints.

`returnId`	`status`	`createdAtUtc`	`orderReference`	`invoiceReference`
11111111-1111-1111-1111-111111111111	`Completed`	2026-09-27	2000000001	9000000001
22222222-2222-2222-2222-222222222222	`Rejected`	2026-09-19	2000000002	9000000002
33333333-3333-3333-3333-333333333333	`Approved`	2026-09-25	2000000003	9000000003
44444444-4444-4444-4444-444444444444	`ItemReceived`	2026-09-22	2000000001	9000000001
66666666-6666-6666-6666-666666666666	`AwaitingApproval`	2026-09-05	2000000001	9000000001

GET /list/applicant/11111111-… — Customer A, no filters (five returns, newest updated first)

{
  "returns": [
    {
      "returnId": "11111111-1111-1111-1111-111111111111",
      "status": "Completed",
      "createdAtUtc": "2026-09-27T13:00:00+00:00",
      "updatedAtUtc": "2026-09-27T13:42:11+00:00",
      "references": { "orderReference": "2000000001", "invoiceReference": "9000000001" }
    },
    {
      "returnId": "33333333-3333-3333-3333-333333333333",
      "status": "Approved",
      "createdAtUtc": "2026-09-25T07:30:00+00:00",
      "updatedAtUtc": "2026-09-25T12:00:00+00:00",
      "references": { "orderReference": "2000000003", "invoiceReference": "9000000003" }
    },
    {
      "returnId": "44444444-4444-4444-4444-444444444444",
      "status": "ItemReceived",
      "createdAtUtc": "2026-09-22T11:00:00+00:00",
      "updatedAtUtc": "2026-09-26T09:40:00+00:00",
      "references": { "orderReference": "2000000001", "invoiceReference": "9000000001" }
    },
    {
      "returnId": "22222222-2222-2222-2222-222222222222",
      "status": "Rejected",
      "createdAtUtc": "2026-09-18T10:02:00+00:00",
      "updatedAtUtc": "2026-09-19T09:11:00+00:00",
      "references": { "orderReference": "2000000002", "invoiceReference": "9000000002" }
    },
    {
      "returnId": "66666666-6666-6666-6666-666666666666",
      "status": "AwaitingApproval",
      "createdAtUtc": "2026-09-05T09:00:00+00:00",
      "updatedAtUtc": "2026-09-05T09:00:00+00:00",
      "references": { "orderReference": "2000000001", "invoiceReference": "9000000001" }
    }
  ],
  "continuationToken": null
}

Filtering by Date Range

CreatedFromUtc/CreatedToUtc match against createdAtUtc. Against Customer A’s list, CreatedFromUtc=2026-09-18&CreatedToUtc=2026-09-25 keeps three returns and drops 11111111-… (created 2026-09-27) and 66666666-… (created 2026-09-05).

GET /list/applicant/11111111-…?CreatedFromUtc=2026-09-18&CreatedToUtc=2026-09-25 → 33333333-…, 44444444-…, 22222222-…

{
  "returns": [
    {
      "returnId": "33333333-3333-3333-3333-333333333333",
      "status": "Approved",
      "createdAtUtc": "2026-09-25T07:30:00+00:00"
    },
    {
      "returnId": "44444444-4444-4444-4444-444444444444",
      "status": "ItemReceived",
      "createdAtUtc": "2026-09-22T11:00:00+00:00"
    },
    {
      "returnId": "22222222-2222-2222-2222-222222222222",
      "status": "Rejected",
      "createdAtUtc": "2026-09-18T10:02:00+00:00"
    }
  ],
  "continuationToken": null
}

Sort Direction

SortDir=Asc returns the same list oldest-created-first when combined with SortBy=CreatedAtUtc.

GET /list/applicant/11111111-…?SortBy=CreatedAtUtc&SortDir=Asc → 66666666-…, 22222222-…, 44444444-…, 33333333-…, 11111111-…

{
  "returns": [
    { "returnId": "66666666-6666-6666-6666-666666666666", "createdAtUtc": "2026-09-05T09:00:00+00:00" },
    { "returnId": "22222222-2222-2222-2222-222222222222", "createdAtUtc": "2026-09-18T10:02:00+00:00" },
    { "returnId": "44444444-4444-4444-4444-444444444444", "createdAtUtc": "2026-09-22T11:00:00+00:00" },
    { "returnId": "33333333-3333-3333-3333-333333333333", "createdAtUtc": "2026-09-25T07:30:00+00:00" },
    { "returnId": "11111111-1111-1111-1111-111111111111", "createdAtUtc": "2026-09-27T13:00:00+00:00" }
  ],
  "continuationToken": null
}

Applicant vs Order vs Invoice

list/applicant/{customerId} returns everything a customer filed; list/order/{orderReference} and list/invoice/{invoiceReference} narrow that down to returns against one specific order or invoice. Order 2000000001 shows the difference:

GET /list/order/2000000001 → 11111111-…, 44444444-…, 66666666-…

{
  "returns": [
    { "returnId": "11111111-1111-1111-1111-111111111111", "references": { "orderReference": "2000000001", "invoiceReference": "9000000001" } },
    { "returnId": "44444444-4444-4444-4444-444444444444", "references": { "orderReference": "2000000001", "invoiceReference": "9000000001" } },
    { "returnId": "66666666-6666-6666-6666-666666666666", "references": { "orderReference": "2000000001", "invoiceReference": "9000000001" } }
  ],
  "continuationToken": null
}

GET /list/invoice/9000000001 → same three returns — the invoice was raised against that one order

{
  "returns": [
    { "returnId": "11111111-1111-1111-1111-111111111111", "references": { "orderReference": "2000000001", "invoiceReference": "9000000001" } },
    { "returnId": "44444444-4444-4444-4444-444444444444", "references": { "orderReference": "2000000001", "invoiceReference": "9000000001" } },
    { "returnId": "66666666-6666-6666-6666-666666666666", "references": { "orderReference": "2000000001", "invoiceReference": "9000000001" } }
  ],
  "continuationToken": null
}

GET /list/applicant/11111111-… → all five returns, across all three orders

{
  "returns": [
    { "returnId": "11111111-1111-1111-1111-111111111111", "references": { "orderReference": "2000000001", "invoiceReference": "9000000001" } },
    { "returnId": "33333333-3333-3333-3333-333333333333", "references": { "orderReference": "2000000003", "invoiceReference": "9000000003" } },
    { "returnId": "44444444-4444-4444-4444-444444444444", "references": { "orderReference": "2000000001", "invoiceReference": "9000000001" } },
    { "returnId": "22222222-2222-2222-2222-222222222222", "references": { "orderReference": "2000000002", "invoiceReference": "9000000002" } },
    { "returnId": "66666666-6666-6666-6666-666666666666", "references": { "orderReference": "2000000001", "invoiceReference": "9000000001" } }
  ],
  "continuationToken": null
}

Error Responses

All three list endpoints share the same error envelope. The code field identifies the error type.

400 — Validation Error

Returned when the path value or a query parameter is invalid. The errors[] array lists each invalid field with a human-readable message.

Path value missing or whitespace — applicant endpoint:

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

Path value missing or whitespace — order endpoint:

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

Path value missing or whitespace — invoice endpoint:

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

PageSize outside the 1–50 range:

{
  "errors": [
    { "fieldName": "Filter.PageSize", "message": "PageSize must be between 1 and 50." }
  ],
  "code": "ERR_VALIDATION_0001",
  "status": 400
}

CreatedFromUtc later than CreatedToUtc:

{
  "errors": [
    { "fieldName": "Filter.CreatedFromUtc", "message": "From cannot be later than To." }
  ],
  "code": "ERR_VALIDATION_0001",
  "status": 400
}

CreatedFromUtc earlier than the minimum supported date:

{
  "errors": [
    {
      "fieldName": "Filter.CreatedFromUtc",
      "message": "From cannot be earlier than 2023-10-14."
    }
  ],
  "code": "ERR_VALIDATION_0001",
  "status": 400
}