Sections in this article:
Public API authentication
The Returns public API uses Basic Authentication. All methods part of the API use the same information for authentication, the username and password for your organization (image showing the use-case from Postman below).
Endpoints
Get List of Return Orders
URL: GET /return-orders
Endpoint returns a list of return orders based on the query string parameters sent in the method.
Parameters:
|
Parameter |
Type |
Required |
|
updatedAfter |
DateTime (ISO Format) |
No |
|
updatedBefore |
DateTime (ISO Format) |
No |
|
createdAfter |
DateTime (ISO Format) |
No |
|
createdBefore |
DateTime (ISO Format) |
No |
Example Call:
GET https://staging.returnado.com/public-api/v3/return-orders?updatedAfter=2022-12-20T01:30:00.
000-05:00&updatedBefore=2022-12-31T01:30:00.000-05:00&createdAfter=2022-12-20T01:30:00.000-05:0
0&createdBefore=2022-12-31T01:30:00.000-05:00
Brings all return orders up updated after 2022/12/20 and before 2022/12/31 and created after 2020/12/20 and before 2022/12/31.
Response
ResponseWrapper:
|
Field |
Type |
Description |
|
records |
ReturnOrder[] |
Records found by search |
|
totalRecords |
integer |
Number of records found |
{
"records": [
{
"returnOrderId": 56373,
"returnOrderExtId": "{}",
"orderId": "249-307",
"createdAt": "2022-12-20T18:02:31Z",
"updatedAt": "2022-12-20T18:02:32Z",
"marketCode": "27001",
"customerId": "john_doe@nshift.com",
"status": "pre_approval",
"currency": "GBP",
"netOriginalTotal": 1198.8,
"taxOriginalTotal": 0,
"grossOriginalTotal": 1198.8,
"netRefundItemsTotal": 999,
"taxRefundItemsTotal": 0,
"grossRefundItemsTotal": 999,
"netShippingFeeRefund": 0,
"taxShippingFeeRefund": 0,
"grossShippingFeeRefund": 0,
"netFeesTotal": 0,
"taxFeesTotal": 0,
"grossFeesTotal": 0,
"netRefundTotal": 999,
"taxRefundTotal": 0,
"grossRefundTotal": 999,
"items": [
{
"returnOrderId": 56373,
"returnOrderExtId": "{}",
"returnOrderItemId": 120808,
"originalOrderItemId": "1",
"productId": "iris",
"productVariantId": "iris",
"originalNetAmount": 999,
"originalTaxAmount": 0,
"originalGrossAmount": 999,
"reportedCondition": "tags_are_intact",
"reclamationReason": "style_doesnt_suit",
"nextAction": "restock",
"status": "pending",
"refundQuantity": 1,
"netRefundAmount": 999,
"taxRefundAmount": 0,
"grossRefundAmount": 999
}
]
}
],
"totalRecords": 1
}
Get Return Order Item by Id
URL: GET /return-orders/{returnOrderId}
Endpoint returns the return order identified by the id used on the url path.
Parameters:
|
Parameter |
Type |
Required |
|
returnOrderId |
integer |
yes |
Example Call:
GET https://staging.returnado.com/public-api/v3/return-orders/56373
Brings the return order that is identified by the 56373 id.
Response:
ReturnOrder
{
"returnOrderId": 56373,
"returnOrderExtId": "{}",
"orderId": "249-307",
"createdAt": "2022-12-20T18:02:31Z",
"updatedAt": "2022-12-20T18:02:32Z",
"marketCode": "27001",
"customerId": "john_doe@nshift.com",
"status": "pre_approval",
"currency": "GBP",
"netOriginalTotal": 1198.8,
"taxOriginalTotal": 0,
"grossOriginalTotal": 1198.8,
"netRefundItemsTotal": 999,
"taxRefundItemsTotal": 0,
"grossRefundItemsTotal": 999,
"netShippingFeeRefund": 0,
"taxShippingFeeRefund": 0,
"grossShippingFeeRefund": 0,
"netFeesTotal": 0,
"taxFeesTotal": 0,
"grossFeesTotal": 0,
"netRefundTotal": 999,
"taxRefundTotal": 0,
"grossRefundTotal": 999,
"items": [
{
"returnOrderId": 56373,
"returnOrderExtId": "{}",
"returnOrderItemId": 120808,
"originalOrderItemId": "1",
"productId": "iris",
"productVariantId": "iris",
"originalNetAmount": 999,
"originalTaxAmount": 0,
"originalGrossAmount": 999,
"reportedCondition": "tags_are_intact",
"reclamationReason": "style_doesnt_suit",
"nextAction": "restock",
"status": "pending",
"refundQuantity": 1,
"netRefundAmount": 999,
"taxRefundAmount": 0,
"grossRefundAmount": 999
}
]
}
Get Returns Summary
URL: GET /returns-summary
The endpoint returns the summary of return orders for the customer requesting them.
Based on the filters, the endpoint can be used to filter only return orders for a specific market (for example only Sweden market if return orders are logged for both UK and Sweden).
The periodStart and periodEnd are applied on the date when the return_order was last updated.
This endpoint also includes pagination. Pagination starts with page 0.
Parameters:
|
Parameter |
Type |
Required |
|
periodStart |
DateTime (ISO Format) |
yes |
|
periodEnd |
DateTime (ISO Format) |
no |
|
marketCode |
integer |
no |
|
pageSize |
integer |
no |
|
pageNumber |
integer |
no |
Example Call:
GET https://staging.returnado.com/public-api/v3/returns-summary?periodStart=2022-12-10T01:30:00
.000-05:00&periodEnd=2022-12-31T01:30:00.000-05:00&marketCode=27001&pageSize=5&pageNumber=1
Brings the orders belonging to the market identified, updated within the mentioned period. Due to pagination, it will skip the first 5 orders (ordered by the return_order_item_id)
Response:
Returns PaginatedResponse<ReturnSummary>
|
Field |
Type |
Required |
|
records |
ReturnSummary[] |
Return Summaries returned by search |
|
totalRecords |
integer |
Number of records found |
|
pagination.totalPages |
integer |
Number of pages spanned by results in current pagination configuration |
|
pagination.currentPage |
integer |
Page to which data currently retrieved belongs |
|
pagination.currentPageSize |
integer |
Number of return order summaries per page that the API is currently bringing |
{
"records": [
{
"marketCode": "27001",
"marketName": "Arena-1",
"customerId": "john_doe_1@gmail.com",
"orderId": "968-309",
"returnOrderId": 56367,
"returnOrderItemId": 120801,
"productId": "hermes",
"productVariantId": "hermes",
"sku": "hermes",
"productName": "hermes",
"currencyCode": "GBP",
"returnedQuantity": 1,
"returnReasonCode": "style_doesnt_suit",
"itemConditionCode": "accessory_missing",
"nextActionCode": "restock",
"originalValueGross": 579,
"returnValueGross": 579,
"reconversionValueGross": 0,
"refundValueGross": 579,
"orderCreatedAt": "2022-12-19T10:19:36Z",
"createdAt": "2022-12-19T10:22:10Z",
"currentState": "awaiting_approval",
"stateUpdatedAt": "2022-12-19T10:22:10Z",
"claim": false,
"refundApproved": false
},
{
"marketCode": "27001",
"marketName": "Arena-1",
"customerId": "john_doe_2@nshift.com",
"orderId": "819-761",
"returnOrderId": 56368,
"returnOrderItemId": 120802,
"productId": "hera",
"productVariantId": "hera",
"sku": "hera",
"productName": "hera",
"currencyCode": "GBP",
"returnedQuantity": 1,
"returnReasonCode": "colour_not_as_expected",
"itemConditionCode": "accessory_missing",
"nextActionCode": "restock",
"originalValueGross": 39,
"returnValueGross": 39,
"reconversionValueGross": 0,
"refundValueGross": 39,
"orderCreatedAt": "2022-12-19T14:57:25Z",
"createdAt": "2022-12-19T14:58:37Z",
"currentState": "awaiting_approval",
"stateUpdatedAt": "2022-12-19T14:58:37Z",
"claim": false,
"refundApproved": false
},
{
"marketCode": "27001",
"marketName": "Arena-1",
"customerId": "john_doe@nshift.com",
"orderId": "249-307",
"returnOrderId": 56373,
"returnOrderItemId": 120808,
"productId": "iris",
"productVariantId": "iris",
"sku": "iris",
"productName": "iris",
"currencyCode": "GBP",
"returnedQuantity": 1,
"returnReasonCode": "style_doesnt_suit",
"itemConditionCode": "tags_are_intact",
"nextActionCode": "restock",
"originalValueGross": 999,
"returnValueGross": 999,
"reconversionValueGross": 0,
"refundValueGross": 999,
"orderCreatedAt": "2022-12-20T17:59:56Z",
"createdAt": "2022-12-20T18:02:31Z",
"currentState": "awaiting_approval",
"stateUpdatedAt": "2022-12-20T18:02:32Z",
"claim": false,
"refundApproved": false
}
],
"totalRecords": 8,
"pagination": {
"totalPages": 2,
"currentPage": 1,
"currentPageSize": 3
}
}The endpoint for ReturnOrderSummary also brings in information regarding the state of the order, as well as the refund state.
Update Return Order Refund Status
URL: PUT /update-return-status/{returnOrderId}
This endpoint is used to update the status of the return order.
Parameters:
|
Field |
Type |
Required |
|
returnOrderId |
bool |
true |
Request Body:
{
"refundSucceeded": true,
"orderId": null,
"errorCode": "e404",
"errorDescription": "insufficient funds"
}
|
Parameter |
Type |
Required |
|
refundSucceeded |
boolean |
yes |
|
orderId |
string |
no |
|
errorCode |
string |
no |
|
errorDescription |
string |
no |
Example call:
PUT https://staging.returnado.com/public-api/v3/update-return-status/56367
Response:
HTTP 200 if the request is completed successfully.
Error codes where appropriate:
For example, if missing refundSucceeded
{
"code": 422,
"error": "Unprocessable Entity",
"message": "Field error in object 'returnOrderUpdateStatusDto' on field 'refundSucceeded':
rejected value [null]; codes [NotNull.returnOrderUpdateStatusDto.refundSucceeded,NotNull.
refundSucceeded,NotNull.java.lang.Boolean,NotNull]; arguments [org.springframework.context
.support.DefaultMessageSourceResolvable: codes [returnOrderUpdateStatusDto.refundSucceeded,
refundSucceeded]; arguments []; default message [refundSucceeded]]; default message [must
not be null]",
"timestamp": "2023-01-16T17:22:05Z"
}