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).
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
      operationId: getReturnedItemsByMerchantId
      x-operation-id-source: derived
components:
  schemas:
    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
    DateTime:
      type: string
      format: date-time
      description: Date time
      example: '2017-07-21T17:32:28Z'
    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
    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
    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
  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.