ZRS Pure Return Stock Movement Overview

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

ZRS Pure items returned by Zalando customers are received at a Zalando return centre, processed and shipped back to the merchant’s warehouse.

Use the ZRS Pure Return Stock Movement API to retrieve the customer order number and the item classification of returned stock items by simply scanning the EAN or quality label via the APl.

Use the ZRS Pure Return Stock Movement API to get the updated list of items with latest status (In process & Shipped) and returned back to the merchant from a Zalando return centre in a given time frame or interval.

Consumers

  • This API can be used by

    • Merchants that are directly connected to the zDirect merchant gateway.
    • Integrators and Technical Partners

  • This API can be used to:

    • Get the returned stock details like Customer Order Number, Item Classification, Site (Zalando return centre location) and other important information by simply providing MerchantId in combination with Quality Label, SSCC or EAN.
    • Get the returned stock items movement updates from the Zalando return centre for a given time interval.

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 Pure Returned Items By MerchantId in combination with Item Identifier, Parcel ID or EAN

Basic requirement for merchants or technical partners is to request for “Returned Item” information by calling ZRS Pure Return Stock Movement API by providing MerchantId in combination with Zalando unique item identifier (Quality Label), Zalando Parcel ID (SSCC), EAN or customer order number.

The request would be authenticated via zDirect.

MerchantId is the mandatory parameter to request “Returned Item” information.

  • MerchantId

With MerchantId, the result can be fetch using below query parameters.

  • Zalando unique item identifier (Quality Label)
  • EAN
  • Zalando Parcel ID (SSCC)

Optionally, the result can be further filtered using “Customer Order Number” as query parameter.

Use cases:

  1. By Zalando unique item identifier (Quality Label): The quality label is a Zalando unique identifier of a processed returned item.
  2. By EAN and SSCC (Zalando parcel ID): The combination of the EAN and the outbound parcel number (from Zalando to the merchant) is a unique identifier to fetch returned item details.
  3. By SSCC (Zalando parcel ID): It will give the merchant the information of the returned items in the entire outbound parcel for them to work with.

HTTP Request 

GET /merchants/{merchant-id}/returns/zrs-pure-items?quality_label={quality_label}&sscc={sscc}&ean={ean}&order_number={order_number}&page_size={page_size}

Using httpie, this call would look like this:

http GET \
https://api-sandbox.merchants.zalando.com/merchants/{merchant-id} \
/returns/zrs-pure-items?quality_label={quality_label}&sscc={sscc}&ean={ean}&order_number={order_number}&page_size={page_size} \
'Authorization: Bearer $YOUR_ACCESS_TOKEN' \
'accept application/json'

Get ZRS Pure Returned Items Updates by MerchantId & Date Range

ZRS Pure Return Stock Movement API provides facility to get the updates of returned items based on the MerchantId & Date Range.

  • MerchantId
  • Last Updated Before
  • Last Updated After

Optionally, the result can be further filtered using below query parameters:

  • Order Number
  • EAN
  • SSCC
  • Quality Label

HTTP Request 

GET /merchants/{merchant-id}/returns/zrs-pure-items?quality_label={quality_label}&sscc={sscc}&ean={ean}&order_number={order_number}&last_updated_before={last_updated_before}&last_updated_after={last_updated_after}&page_size={page_size}

Using httpie, this call would look like this:

http GET \
https://api-sandbox.merchants.zalando.com/merchants/{merchant-id} \
/returns/zrs-pure-items?quality_label={quality_label}&sscc={sscc}&ean={ean}&order_number={order_number} \
&last_updated_before=2024-02-08T00:50:17.881Z&last_updated_after=2024-02-08T12:41:17.881Z&page_size=50 \
'Authorization:Bearer $YOUR_ACCESS_TOKEN' \
'accept application/json'

Response: Successful

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

{
  "items": [
    {
      "order_number": "11404000110011",
      "quality_label": "00015S3ZKE9",
      "item_classification": "A_GOODS",
      "merchant_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "sales_channel_id": "7f4329e6-ae41-4d73-b542-47de90d2ce4f",
      "sscc": "00040002762581192400",
      "ean": "8051101111000",
      "logistic_service": "Zalando Partner Returns",
      "status": "SHIPPED",
      "site": "madrid-spk-1",
      "item_returned_at": "2024-02-08T09:57:44.230Z",
      "shipped_to_partner_at": "2024-02-08T09:57:44.230Z",
      "last_updated_at": "2024-02-08T09:57:44.230Z"
    }
  ],
  "links": {
    "self": "/merchants/merchantX/returns/zrs-pure-items?...",
    "next": "/merchants/merchantX/returns/zrs-pure-items?..."
  }
}

Understanding API Response

The API response is a paginated component with two parts:

  • A list of Returned Stock Items called "items" with maximum default page size 100. Page size is one of the query parameters in the request.
  • Returned Items will appear in a natural order in the timeline when updates to them happen in the Return Centre.

In the response “status” you get the latest status of the item. The status value can be

  • In Process: The item has been received and is in process
  • Shipped: The item has been dispatched from the Zalando site and is on its way to the designated return address provided by the merchant.

In the response “site” you get the outbound location from where the returned item has been shipped to the merchant. The value will be available for SHIPPED items only.

A "links" object which will hold a resource link referring to the page

  • "self": Resource link with current page.
  • "next": Resource link of next page.

Example:

{
  "items": [
    {
      "order_number": "11404000110011",
      "quality_label": "00015S3ZKE9",
      "item_classification": "A_GOODS",
      "merchant_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "sales_channel_id": "7f4329e6-ae41-4d73-b542-47de90d2ce4f",
      "sscc": "00040002762581192400",
      "ean": "8051101111000",
      "logistic_service": "Zalando Partner Returns",
      "status": "SHIPPED",
      "site": "madrid-spk-1",
      "item_returned_at": "2024-02-08T09:57:44.230Z",
      "shipped_to_partner_at": "2024-02-08T09:57:44.230Z",
      "last_updated_at": "2024-02-08T09:57:44.230Z"
    }
  ],
  "links": {
    "self": "/merchants/merchantX/returns/zrs-pure-items?...",
    "next": "/merchants/merchantX/returns/zrs-pure-items?..."
  }
}

Response: Error

You may get a http 400 - Bad Request response in the following cases:

  1. If the required query parameter merchant-id is absent or merchant-id is not a valid UUID format.
  2. If the query parameter “last_updated_after” date is later than “last_updated_before” date.
  3. If query parameters “last_updated_after” & “last_updated_before” are future dates.
  4. If requested “page_size” is more than 1200.
  5. If one of the query parameters is not provided i.e. last_updated_after & last_updated_before, quality_label, sscc, ean and order_number

Additional Resources

Contact Support