Zalando AnnouncedReturns API

openapi: 3.0.2
info:
  title: Article Requirements AnnouncedReturns API
  version: 1.0.0
  x-audience: external-merchant
  x-api-id: e655a9cb-4cda-466d-a552-13a50c4b02ae
  description: 'This API provides endpoints to retrieve UAF article requirement outlines, attribute types, and attribute values for a given business partner. This API is in pilot phase and only available to a limited set of partners.

    '
tags:
- name: AnnouncedReturns
paths:
  /merchants/{merchant-id}/announced-returns:
    get:
      summary: Retrieve the returns announced by customers via Zalando website.
      description: Retrieve the returns announced by customers via Zalando website. Currently we only retrieve the announced returns that will be delivered using a return label generated from Zalando website, see 'type' attribute in the AnnouncedReturn object.
      parameters:
      - $ref: '#/components/parameters/Authorization'
      - $ref: '#/components/parameters/x-flow-id'
      - $ref: '#/components/parameters/merchantId'
      - $ref: '#/components/parameters/salesChannelId'
      - $ref: '#/components/parameters/cursor'
      - $ref: '#/components/parameters/conventionalLimit'
      - name: after
        in: query
        description: Query filter returning the returns announced after the given timestamp (inclusive). The timestamp is in the ISO 8601 format. The Date and time are separated by the "T" literal, and the Time and Timezone are separated by the "+" literal. For UTC time, you should simply use "Z" as the suffix, for other cases use URL encoding for the "+" literal.
        required: false
        example: '2019-07-01T06:55:47Z'
        schema:
          type: string
          format: date-time
      - name: before
        in: query
        description: Query filter returning the returns announced before the given timestamp (exclusive). The timestamp is in the ISO 8601 format. The Date and time are separated by the "T" literal, and the Time and Timezone are separated by the "+" literal. For UTC time, you should simply use "Z" as the suffix, for other cases use URL encoding for the "+" literal.
        required: false
        example: '2019-07-01T07:55:47Z'
        schema:
          type: string
          format: date-time
      - name: sort
        in: query
        description: Sorting attributes separated by a comma. Default order (without sign symbol '+' or '-') is ascending(+). Minus(-) should be used in front of an attribute name if you want descending order. The parameter value includes the attributes (separated by a comma) that the query parameter 'sort' will apply to. Currently we only support sorting on return_registered_at.
        required: false
        schema:
          type: string
          default: -return_registered_at
      security:
      - merchant_platform:
        - orders/read
      tags:
      - AnnouncedReturns
      responses:
        '200':
          description: Retrieves a list of the announced returns.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/AnnouncedReturns'
        '429':
          description: Exceeded the rate limit.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/RateLimitError'
          headers:
            X-Flow-Id:
              type: string
              description: Unique identifier for the request
            Retry-After:
              type: string
              description: Specifies how long you must wait before making a new request, in seconds
            X-Rate-Limit:
              type: string
              description: Shows the limit for the operation that you are performing
        default:
          $ref: '#/components/responses/Default'
components:
  schemas:
    AnnouncedReturn:
      type: object
      description: A return announced by a customer via Zalando website. It's possible that a single announced return contains items from multiple orders.
      required:
      - announced_return_id
      - sales_channel_id
      - return_tracking_number
      - type
      - orders
      - return_registered_at
      properties:
        announced_return_id:
          type: string
          format: uuid
          description: Unique identifier of an announced return.
          example: bf48ba35-149d-4b76-8ac9-d08d126b517f
        sales_channel_id:
          type: string
          format: uuid
          description: Unique identifier of a sales channel.
          example: bf48ba35-149d-4b76-8ac9-d08d126b517f
        return_tracking_number:
          type: string
          description: a tracking number to track the return delivery.
          example: '744374997468'
        type:
          type: string
          description: 'The type of the announced return, defined as an extensible enum: * ZALANDO_ONLINE_CREATED - Denotes an announced return to be delivered using a return label generated through the Zalando Website. A return label is generated when a customer announces a return on the Zalando shopping website.'
        orders:
          type: array
          description: Order information in the announced return.
          items:
            $ref: '#/components/schemas/AnnouncedReturnOrder'
        return_registered_at:
          description: The timestamp of the return label generation.
          type: string
          format: date-time
          example: '2014-12-31T23:00:00.000Z'
    Errors:
      type: object
      description: An array of error objects.
      properties:
        errors:
          description: All errors.
          type: array
          items:
            $ref: '#/components/schemas/Error'
    RateLimitError:
      type: object
      description: Error object for rate limit.
      properties:
        message:
          description: A string containing the error message for exceeding the rate limit
          type: string
    Error:
      type: object
      description: Error object
      properties:
        status:
          description: The HTTP status code applicable to this problem, expressed as a string value.
          type: string
          example: 404
        code:
          description: An application-specific error code, expressed as a string value.
          type: string
          example: 123A
        title:
          description: A short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization.
          type: string
          example: The resource requested could not be found.
        detail:
          description: A human-readable explanation specific to this occurrence of the problem.
          type: string
          example: The order 123 does not exist.
        source:
          $ref: '#/components/schemas/ErrorSource'
    AnnouncedReturns:
      type: object
      required:
      - data
      - links
      description: A collection of returns announced by customers via Zalando website.
      properties:
        data:
          type: array
          description: An array of returns announced by customers via Zalando website.
          items:
            $ref: '#/components/schemas/AnnouncedReturn'
        links:
          $ref: '#/components/schemas/BaseLinks'
    AnnouncedReturnOrderLine:
      type: object
      description: The Order Line information in the announced return.
      required:
      - order_line_id
      - order_item_id
      - return_reason
      properties:
        order_line_id:
          type: string
          format: uuid
          description: Unique identifier of an Order Line.
          example: bf48ba35-149d-4b76-8ac9-d08d126b517f
        order_item_id:
          type: string
          format: uuid
          description: Unique identifier of the Order Item this Order Line belongs to.
          example: bf48ba35-149d-4b76-8ac9-d08d126b517f
        return_reason:
          type: string
          description: 'The reason for returning this order line, for example TOO_LARGE, TOO_SMALL, or DONT_LIKE.


            Note: this is a free-form string and is not limited to a predefined set of return reasons or a specific format.

            '
    ErrorSource:
      type: object
      description: Indicate the source of error.
      properties:
        pointer:
          description: A JSON Pointer [RFC6901] to the associated entity in the request document, for example, '/data' for a primary data object, or '/data/attributes/title' for a specific attribute.
          type: string
          example: /data/attributes/order_number
        parameter:
          description: A string indicating which URI query parameter caused the error.
          type: string
          example: order_number
    BaseLinks:
      type: object
      required:
      - self
      description: Links for cursor-based navigation.
      properties:
        prev:
          description: Simplified hypertext control referencing the previous page. If this link is absent, there is no previous page to iterate.
          type: string
          format: uri
          example: https://api-sandbox.merchant-center.zalan.do/resources?cursor=Y3Vyc29yCg
        self:
          description: Simplified hypertext control referencing the current page.
          type: string
          format: uri
          example: https://api-sandbox.merchants.zalando.com/resources?cursor=Y3Vyc29yCg
        next:
          description: Simplified hypertext control referencing the next page. If this link is absent, there is no next page to iterate. In rare cases the next link may return an empty collection.
          type: string
          format: uri
          example: https://api-sandbox.merchants.zalando.com/resources?cursor=Y3Vyc29yCg
    AnnouncedReturnOrder:
      type: object
      description: The Order information in the announced return.
      required:
      - order_id
      - order_number
      properties:
        order_id:
          type: string
          format: uuid
          description: Unique identifier of an Order.
          example: bf48ba35-149d-4b76-8ac9-d08d126b517f
        order_number:
          type: string
          description: Zalando's unique order identifier.
          example: '1040970000502251'
        merchant_order_id:
          type: string
          description: Merchant's unique order identifier.
          example: '1040970000502251'
        order_lines:
          type: array
          minItems: 1
          description: Order lines being returned within this order.
          items:
            $ref: '#/components/schemas/AnnouncedReturnOrderLine'
  parameters:
    Authorization:
      name: Authorization
      in: header
      description: Bearer access token.
      required: true
      schema:
        type: string
        format: JWT token
    conventionalLimit:
      name: limit
      in: query
      description: Query filter specifying the upper limit to the number of entries on a page.
      required: false
      schema:
        type: integer
        default: 50
    merchantId:
      name: merchant-id
      in: path
      description: To identify a merchant for which this operation is carried out.
      required: true
      schema:
        type: string
        format: uuid
    cursor:
      name: cursor
      in: query
      description: Query filter specifying an opaque pointer to a page.
      required: false
      schema:
        type: string
      example: Y3Vyc29yCg
    salesChannelId:
      name: sales_channel_id
      in: query
      description: Query filter specifying a sales channel.
      required: false
      schema:
        type: string
        format: uuid
    x-flow-id:
      name: X-Flow-Id
      in: header
      description: Used for troubleshooting.
      required: false
      schema:
        type: string
        format: uuid
      x-doc:
        excluded: true
  responses:
    Default:
      description: error occurred - see status code and error/problem objects for more information.
      content:
        application/vnd.api+json:
          schema:
            $ref: '#/components/schemas/Errors'
        application/problem+json:
          schema:
            $ref: https://opensource.zalando.com/restful-api-guidelines/models/problem-1.0.1.yaml#/Problem