Returns (admin API)

Admin routes of the returns module. Every route needs a staff session and the permission named on it; send X-Resolve-Locale: false to receive every locale of a translatable field for editing.

GET /v1/admin/returns

List returns (admin)

Parameters:

• customerId in query (string, optional).
• dateFrom in query (string, optional).
• dateTo in query (string, optional).
• page in query (number, min 1, optional).
• pageSize in query (number, min 1, optional).
• reason in query ("CHANGED_MIND", "DEFECTIVE", "NOT_AS_DESCRIBED", "OTHER", "WRONG_SIZE", optional).
• sortBy in query (string, optional).
• sortOrder in query ("asc", "desc", optional).
• status in query ("APPROVED", "CLOSED", "ITEM_RECEIVED", "REFUND_PROCESSED", "REJECTED", "REQUESTED", optional).

Responses:

• 200: Returns retrieved.
• 401: Unauthorized.
• 403: Insufficient permissions.

GET /v1/admin/returns/{id}

Get return by ID (admin)

Parameters:

• id in path (string, required).

Responses:

• 200: Return retrieved.
• 401: Unauthorized.
• 403: Insufficient permissions.
• 404: Return not found.

PATCH /v1/admin/returns/{id}/approve

Approve return

Parameters:

• id in path (string, required).

Responses:

• 200: Return approved.
• 401: Unauthorized.
• 403: Insufficient permissions.
• 404: Return not found.

PATCH /v1/admin/returns/{id}/close

Close return

Parameters:

• id in path (string, required).

Responses:

• 200: Return closed.
• 401: Unauthorized.
• 403: Insufficient permissions.
• 404: Return not found.

PATCH /v1/admin/returns/{id}/receive

Receive return

Parameters:

• id in path (string, required).

Request body: ReceiveReturnDto.

Responses:

• 200: Return received.
• 400: Invalid input.
• 401: Unauthorized.
• 403: Insufficient permissions.
• 404: Return not found.

PATCH /v1/admin/returns/{id}/refund

Process return refund

Parameters:

• id in path (string, required).

Request body: RefundReturnDto.

Responses:

• 200: Refund processed.
• 400: Invalid input.
• 401: Unauthorized.
• 403: Insufficient permissions.
• 404: Return not found.

PATCH /v1/admin/returns/{id}/reject

Reject return

Parameters:

• id in path (string, required).

Request body: RejectReturnDto.

Responses:

• 200: Return rejected.
• 400: Invalid input.
• 401: Unauthorized.
• 403: Insufficient permissions.
• 404: Return not found.

GET /v1/admin/returns/analytics

Get returns analytics

Parameters:

• dateFrom in query (string, optional).
• dateTo in query (string, optional).

Responses:

• 200: Analytics retrieved.
• 401: Unauthorized.
• 403: Insufficient permissions.

Schemas

ReceiveReturnDto

• items (array of ReceiveReturnItemDto, required).

ReceiveReturnItemDto

• returnItemId (string, required).
• restockDecision ("DAMAGED", "DISPOSE", "RESTOCK", required).
• notes (string, max length 500, optional).

RefundReturnDto

• refundMethod ("EXCHANGE", "ORIGINAL_PAYMENT", "STORE_CREDIT", required).
• notes (string, max length 1000, optional).

RejectReturnDto

• reason (string, min length 1, max length 1000, required).