Zalando Returned Items API

openapi: 3.2.0
info:
  version: 4.2.0
  x-api-id: cc2c30ca-2969-403e-87b1-e27df78ed655
  x-audience: external-partner
  title: zDirect Platform ZFS Stock Movements Returned Items API
  description: "The Stock Movements API is a service offered by Zalando Fulfillment Solutions (ZFS).\n\nThe API makes ZFS business to business movements processes more transparent for partners.\nThe API enables increased transparency for:\n  - Inbound receive process\n  - Outbound return process\n  - Liquidation Data\n\n!!! note\n\n  The retention time for data in this service is 100 days. After that, data may be deleted without notice.  \n  Please note that this limitation has been removed for `GET /reports/received-items/{merchant-id}` endpoint. Now it is the current year and previous year.\n\n\n## Inbound receive process\n\nThe inbound receive process is the process of receiving items in the warehouse (goods receipt) that were delivered by any partner.\n\nEvery item will get a unique ID the Quality Label (QL) that later identifies the item through all warehouse processes.\n\n## Outbound return process\n\nThe outbound return process is the process of returning items from the warehouse to the owning partner.\n\nThe information is enhanced by the quality of the good, if it is known.\n\n## Liquidation Data\n\n  This call returns all items that have been liquidated for a merchant within a specified time frame.\n\n```http\n  GET /zfs/stock-movements/liquidated-items/{merchant_ID}?from=$FROM_DATE&to=$TO_DATE&purchase_order_number=$PURCHASE_ORDER_NUMBER\n```\n  **Note that>>**\n\n  In exceptional scenarios such as system lags or integration delays,\nthere is a possibility that `From` & `To` dates may not fecth 100% items which were liquidated in that duration. In such cases, we request you to retry the report in next 48 hours.\n\n## Fetch strategy\n\nTo get a constant stream of received events the partner has to call the endpoint in regular intervals.\nThe client has to ensure that the intervals (`from` and `to` query parameter) will not lead to data gaps on client side.\n\nSo partners can:\n\n  * build a complete copy of received/returned items in it's database\n  * Can read a \"constant\" stream of item receive/return information\n\nLimitations / Suggestions:\n\n  * Use `GET /returned-items/{merchant_id}?from=&to=` endpoint\n  * Use fetch intervals between 15 and 60 minutes, this ensures that:\n    * the data sets are not too big\n    * the partner get regular updates\n  * The request intervals must not have gaps in between\n  * Request intervals are allowed to overlap. The client has to ensure to not consume received items more than once.\n    * The `quality_label` is unique. It should be used to ensure to not consume `receive-items` more than once.\n  * The query field `from` and `to` relates to `consumed_timestamp`\n  * In case of every non `200` response the result should be ignored and refetched after interval of at least 2 minutes.\n\n## Fetch strategy for the received items endpoint\n\nReceived items endpoint uses a cursor based pagination to fetch the data. Partners do\nnot have to split requested time interval to smaller chunks. Thus we recommend the following way to retrieve the data:\n  * Use `GET /reports/received-items/{merchant_id}` endpoint without cursor query parameter\n  * Use received cursor (if not empty) from the response to fetch the next page of data (include the cursor in the next request)\n  * Repeat the previous step until the cursor in the response is empty"
servers:
- url: api.merchants.zalando.com/zfs/stock-movements
  description: Production instance
- url: api-sandbox.merchants.zalando.com/zfs/stock-movements
  description: Sandbox instance for merchant center
tags:
- name: Returned Items
paths:
  /returned-items/{merchant-id}:
    get:
      summary: Returns returned items
      description: Returns all items returned from Zalando warehouses to the specified partner in the given timeframe.
      security:
      - OAuth2:
        - zfs/returned-item/read
      parameters:
      - in: path
        name: merchant-id
        schema:
          type: string
          format: uuid
        description: Merchant ID
        required: true
      - in: query
        name: from
        schema:
          $ref: '#/components/schemas/DateTime'
        description: Start timestamp for the query, restricted to now minus 100 days
        required: true
      - in: query
        name: to
        schema:
          $ref: '#/components/schemas/DateTime'
        description: End timestamp for the query, restricted to now minus 100 days
        required: true
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/returnedItemsQueryResult'
        default:
          description: A specific error occurred - see status code for more information.
          content:
            application/problem+json:
              schema:
                $ref: https://opensource.zalando.com/problem/schema.yaml#/Problem
      tags:
      - Returned Items
components:
  schemas:
    Address:
      type: object
      description: Destination address to which the items are sent.
      properties:
        city:
          type: string
        country_code:
          type: string
        first_name:
          type: string
        last_name:
          type: string
        salutation:
          type: string
        street:
          type: string
        zip:
          type: string
      required:
      - city
      - country_code
      - first_name
      - last_name
      - salutation
      - street
      - zip
    DateTime:
      type: string
      format: date-time
      description: Date time
      example: '2017-07-21T17:32:28Z'
    returnedItem:
      type: object
      description: Returned Item
      properties:
        merchant_b2b_reference:
          type:
          - string
          - 'null'
          maxLength: 100
          description: A merchant specific optional reference id or information for the advice (for example a merchant's order name or number)
          example: reference
        ean:
          $ref: '#/components/schemas/Ean13'
        parent:
          type:
          - object
          - 'null'
          properties:
            id:
              type: string
              example: '12'
          description: Either a loading unit container (box) or `null`
          required:
          - id
        quality_label:
          type: string
          description: A unique identifier per EAN per item.
          example: 00014D02W8V
        location_id:
          type: string
          format: uuid
          description: Location ID of the warehouse that was returning the item.
          example: 29809185-6a98-4691-a15b-e8d16839b6e8
        shipped_timestamp:
          allOf:
          - $ref: '#/components/schemas/DateTime'
          description: Timestamp when actual return has happened.
        consumed_timestamp:
          allOf:
          - $ref: '#/components/schemas/DateTime'
          description: This timestamp represent the time the data record was made available through our system. It can deviate from `shipped_timestamp` and relates directly to the query params `from`/ `to`.
        zalando_shipment_number:
          type: string
          pattern: ^[0-9]{16}$
          description: An ID identifiying the return-to-partner tour.
          example: '1234567890123456'
        destination:
          allOf:
          - $ref: '#/components/schemas/Address'
          description: Delivery destination address details.
        quality_category:
          description: Defines the quality of an item.
          type: string
          x-extensible-enum:
          - A
          - B
          - C
          - D
        defect_levels:
          allOf:
          - $ref: '#/components/schemas/DefectLevels'
          description: Hierarchical defect description of defected items.
      required:
      - consumed_timestamp
      - ean
      - merchant_b2b_reference
      - quality_label
      - shipped_timestamp
      - zalando_shipment_number
      - location_id
      - quality_category
      - destination
      - defect_levels
      - parent
    returnedItemsQueryResult:
      type: object
      properties:
        returned_items:
          type: array
          items:
            $ref: '#/components/schemas/returnedItem'
    Ean13:
      type: string
      format: ean
      pattern: ^[0-9]{13}$
      maxLength: 13
      description: A 13-digit EAN
      example: 0191476239145
    DefectLevels:
      type: object
      description: Defines a detailed summary of the defect reason.
      properties:
        level_1:
          type: string
          description: defines a brief summary of the defect reason, not always present
        level_2:
          type: string
          description: defines a detailed summary of the defect reason, not always present
      required:
      - level_1
      - level_2
  securitySchemes:
    merchant_platform:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://api-sandbox.merchants.zalando.com/auth/token
          scopes:
            zfs/received-item/read: Access to ZFS received items of a merchant.
            zfs/returned-item/read: Access to ZFS returned items of a merchant.