Pull API – nShift Help Center

Sections in this article:

Public API authentication
Endpoints

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"
}

nShift Help Center

Public API authentication

Endpoints

Get List of Return Orders

Get Return Order Item by Id

Get Returns Summary

Update Return Order Refund Status

Related articles