ZRS Customer Returned Items Overview

This API is intended for use with "Zalando Return Solutions" (ZRS PURE / ZRS PLUS).

This API is for use with ZRS Pure and ZRS Plus only.

Use the ZRS Customer Returned Items API to fetch the list of customer returned items received by a Zalando return center in a given timeframe.

The customer returned items data will be retained from the start of last fiscal (financial) year. Therefore, customer returned items data will be kept for last 1-2 years. After that, data might be deleted without prior notice.

Moreover, returned items will be pushed to the database each morning and will not include today's returned items.

Consumers

  • This API can be used by:
    • merchants who are directly connected to the zDirect Merchant Gateway.
    • integrators and technical partners.
  • This API can be used to:
    • fetch the list of customer returned items received by Zalando return centers for a given time interval.
    • support technical partners (as complimentary) who are currently using zDirect Orders API to fetch order information, but lack information on returned items.
    • update the status of the corresponding order and match it against the returned item details (thanks to the customer order number).

Authentication

The zDirect API requires OAuth 2.0 authentication for all API calls. Use the Authentication API to generate access tokens as described in the Authentication section.

Get ZRS Customer Returned Items

Consumers (merchants, integrators, or technical partners) need to request for the list of customer returned items by calling ZRS Customer Returned Items API and providing the Merchant ID with a date range.

The Request would be authenticated via zDirect.

Request

GET /zrs/merchants/{merchant_id}/customer-returned-items?date_between={date_between}&page={page}&limit={limit}

Here is the HTTP request parameters detail:

Parameter Name Parameter Type Description Required Default Value Conditions
merchant_id Path Variable Merchant ID Yes - UUID
date_between Query Parameter Inclusive start date and exclusive end date Yes - Pattern: YYYY-MM-DD/YYYY-MM-DD
page Query Parameter Pagination page number No 0 Min: 0
limit Query Parameter Pagination page size No 20 Min: 1, Max: 50

Please note merchant_id and date_between parameters are mandatory.

Using httpie, this call would look like this:

http GET \
https://api-sandbox.merchants.zalando.com/zrs\
/merchants/{merchant_id}/customer-returned-items?date_between=2024-01-01/2024-02-01&page=1&limit=50 \
"Authorization: Bearer $YOUR_ACCESS_TOKEN" \
"Accept: application/json"

Response: Successful

You will receive an HTTP 200 reply to a successful request. Example:

{
  "returned_items": [
    {
      "returned_at": "2024-02-07T11:12:25.272Z",
      "ordered_at": "2024-02-07T11:12:25.272Z",
      "return_center_country": "IT",
      "sales_channel_country": "GE",
      "return_center": "Zalando Logistics Erfurt",
      "order_number": "123456789",
      "ean": "1234567890123",
      "quality_label": "0002L01KB8E",
      "simple_sku": "TO123456E-A123456789",
      "shipment_number": "1234567890123456",
      "item_classification": "A_GOODS",
      "article_processing": "OFFER_TO_CUSTOMERS"
    }
  ]
}

Successful response will return the following fields:

Field Description
returned_at Date when an article is scanned for the first time at a Zalando Return Center
ordered_at Date when the customer placed an order containing the partner article
return_center_country The return center's country where the article was returned
sales_channel_country The country where the article was sold in
return_center The return center's name where the article was returned
order_number Order Number
ean A 13-digit EAN
quality_label A unique identifier per EAN per item
simple_sku Simple SKU number
shipment_number Shipment number of the parcel sent to the customer by partner
item_classification Classification of returned item which can be DEFECTIVE or A_GOODS
article_processing Result of article processing which can be SHIP_TO_PARTNER (for ZRS Pure) or OFFER_TO_CUSTOMERS (for ZRS Plus)

Response: Error

An unsuccessful query might return the following HTTP error codes:

  • 400 - Bad Request Invalid request parameters (for instance, invalid page or limit value)
  • 404 - Not Found Incorrect URL or merchant_id
  • 500 - Internal Server Error Unknown Internal Server Error

With any error, a json body describing the problem is returned. For example, the following reply indicates that an invalid page value was provided:

{
  "title": "Bad Request",
  "status": 400,
  "detail": "Invalid page value"
}

Additional Resources

Contact Support