Zalando Orders API

openapi: 3.0.2
info:
  title: Article Requirements AnnouncedReturns Orders 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: Orders
paths:
  /merchants/{merchant-id}/orders:
    get:
      summary: Retrieves the merchant orders. Allows filtering of the orders by creation and modified date.
      description: Retrieves all the orders for the merchant that match the query parameters given. The retention period for orders data is 1 year. All the orders older than this period are not accessible in this endpoint. The response displays all the relevant information for each order.
      parameters:
      - $ref: '#/components/parameters/Authorization'
      - $ref: '#/components/parameters/x-flow-id'
      - $ref: '#/components/parameters/merchantId'
      - $ref: '#/components/parameters/ordersInclude'
      - $ref: '#/components/parameters/page'
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/sort'
      - $ref: '#/components/parameters/salesChannelId'
      - name: created_after
        in: query
        description: All orders created after 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-01T06:55:47Z'
        schema:
          type: string
          format: date-time
      - name: created_before
        in: query
        description: All orders created 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: last_updated_after
        in: query
        description: All orders updated after 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: 2017-01-01T09:11:48%2B01:00
        schema:
          type: string
          format: date-time
      - name: last_updated_before
        in: query
        description: All orders updated 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: 2017-01-01T10:11:48%2B01:00
        schema:
          type: string
          format: date-time
      - name: order_status
        in: query
        description: All orders of a given status (possible values are defined in OrderStatus definition).
        required: false
        schema:
          type: string
      - name: order_number
        in: query
        description: Exact Zalando order number to filter against.
        required: false
        schema:
          type: string
      - name: locale
        in: query
        description: All orders sold in the locale.
        required: false
        schema:
          type: string
      - name: exported
        in: query
        description: Filter orders that have already been exported or not.
        required: false
        schema:
          type: boolean
      - name: order_type
        in: query
        description: 'All orders of a given type (possible values are: PartnerFulfilled, ZalandoFulfilled).'
        required: false
        schema:
          type: string
      security:
      - merchant_platform: []
      tags:
      - Orders
      responses:
        '200':
          description: Retrieves the filtered order list.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/OrdersTopLevel'
        '403':
          description: The privileges of the token are insufficient to retrieve orders for this merchant.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/Errors'
        '404':
          description: Merchant was not found.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/Errors'
        '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:
          description: An array of error objects.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/Errors'
  /merchants/{merchant-id}/orders/{order-id}:
    get:
      summary: Retrieves an order by order-id.
      description: Retrieves all order information for a given order-id.
      parameters:
      - $ref: '#/components/parameters/Authorization'
      - $ref: '#/components/parameters/x-flow-id'
      - $ref: '#/components/parameters/merchantId'
      - $ref: '#/components/parameters/ordersInclude'
      - name: order-id
        in: path
        description: Identifier of the order to retrieve.
        required: true
        schema:
          type: string
          format: uuid
      security:
      - merchant_platform:
        - orders/read
      tags:
      - Orders
      responses:
        '200':
          description: Order with given order-id was found and will be returned.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/OrderTopLevel'
        '403':
          description: The privileges of the token are insufficient to retrieve orders for this merchant.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/Errors'
        '404':
          description: Merchant order was not found.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/Errors'
        '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:
          description: Errors object
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/Errors'
    patch:
      summary: Partially updates the order.
      description: Used to update certain order fields like merchant order-id and tracking information. The retention period for orders data is 1 year. All the orders older than this period are not available for updates in this endpoint.
      security:
      - merchant_platform:
        - orders/write
      tags:
      - Orders
      parameters:
      - $ref: '#/components/parameters/Authorization'
      - $ref: '#/components/parameters/x-flow-id'
      - $ref: '#/components/parameters/merchantId'
      - name: order-id
        in: path
        description: Identifier of the order to patch.
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        description: Patch of the order.
        required: true
        content:
          application/vnd.api+json:
            schema:
              $ref: '#/components/schemas/OrderUpdateTopLevel'
      responses:
        '204':
          description: Order was successfully patched.
          headers:
            Location:
              description: The URL of the patched order.
              schema:
                type: string
                format: url
        '400':
          description: Error in the payload - wrong format or missing fields, see error object for more details.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/Errors'
        '403':
          description: Operation not allowed, or the privileges of the token are insufficient to update this order.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/Errors'
        '404':
          description: Merchant order was not found.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/Errors'
        '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:
          description: Errors object
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/Errors'
  /merchants/{merchant-id}/orders/{order-id}/transitions:
    get:
      summary: Retrieves all state transitions for a given order-id.
      description: Retrieves transitions related to the order including the original state, the final state, the date at which the state transition happened and the user who modified it.
      parameters:
      - $ref: '#/components/parameters/Authorization'
      - $ref: '#/components/parameters/x-flow-id'
      - $ref: '#/components/parameters/merchantId'
      - name: order-id
        in: path
        description: The identifier of the order for which transitions are being requested.
        required: true
        schema:
          type: string
          format: uuid
      security:
      - merchant_platform:
        - orders/read
      tags:
      - Orders
      responses:
        '200':
          description: State transitions were found and will be returned in the answer.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/TransitionsTopLevel'
        '403':
          description: The privileges of the token are insufficient to retrieve orders for this merchant.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/Errors'
        '404':
          description: Merchant order was not found.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/Errors'
        '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:
          description: Errors object
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/Errors'
  /merchants/{merchant-id}/orders/{order-id}/shipments:
    get:
      summary: Get shipments for the order
      description: Retrieves all shipments associated with the order. Each order has at least one shipment (the default), which includes all of its order lines
      parameters:
      - $ref: '#/components/parameters/Authorization'
      - $ref: '#/components/parameters/x-flow-id'
      - $ref: '#/components/parameters/merchantId'
      - name: order-id
        in: path
        description: The identifier of the order on which operations are being requested on.
        required: true
        schema:
          type: string
          format: uuid
      security:
      - merchant_platform:
        - orders/read
      tags:
      - Orders
      responses:
        '200':
          description: Shipments were found and will be returned in the answer.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/Shipments'
        '403':
          description: The privileges of the token are insufficient to retrieve orders for this merchant.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/Errors'
        '404':
          description: Merchant order was not found.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/Errors'
        '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
    post:
      summary: Create a shipment.
      description: Creates a shipment object in preparation for shipping the order. A shipment defines the specific order lines to be shipped together and plays a central role in the fulfillment process. If any order line is already assigned to another shipment, it will be automatically removed from that shipment and assigned to the current one
      parameters:
      - $ref: '#/components/parameters/Authorization'
      - $ref: '#/components/parameters/x-flow-id'
      - $ref: '#/components/parameters/merchantId'
      - name: order-id
        in: path
        description: The identifier of the order on which operations are being requested on.
        required: true
        schema:
          type: string
          format: uuid
      security:
      - merchant_platform:
        - orders/write
      tags:
      - Orders
      requestBody:
        description: The request body contains the information of the shipment
        required: true
        content:
          application/vnd.api+json:
            schema:
              type: object
              required:
              - order_lines
              - weight
              properties:
                merchant_specified_shipment_id:
                  type: string
                  description: Shipment id used by the partner
                order_lines:
                  type: array
                  items:
                    $ref: '#/components/schemas/ShipmentOrderLine'
                weight:
                  $ref: '#/components/schemas/Weight'
                outbound_logistic_center_id:
                  description: Optional unique identifier of the outbound logistic center.
                  type: string
                  format: uuid
                  example: 57be9d4a-28d6-4b83-94de-b784899cabc9
                tracking_number:
                  type: string
                  example: 003403418039972556
                return_tracking_number:
                  type: string
                  example: ReTurNTracKINGNumBER123461413
      responses:
        '201':
          description: Shipment was created successfully.
          content:
            application/vnd.api+json:
              schema:
                type: object
                required:
                - shipment_id
                properties:
                  shipment_id:
                    description: Identifier of the created shipment.
                    type: string
                    format: uuid
                    example: ff8cd551-3642-4ba5-91e4-d75b652d06e6
        '400':
          description: Error in the payload - wrong format or missing fields, see error object for more details.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/Errors'
        '403':
          description: The specified update operation is not allowed or the write permissions are missing for this merchant.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/Errors'
        '404':
          description: Merchant order was not found.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/Errors'
        '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:
          description: Errors object
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/Errors'
  /merchants/{merchant-id}/orders/{order-id}/shipments/{shipment-id}:
    get:
      summary: Get an individual shipment
      description: Retrieves a specific shipment object
      parameters:
      - $ref: '#/components/parameters/Authorization'
      - $ref: '#/components/parameters/x-flow-id'
      - $ref: '#/components/parameters/merchantId'
      - name: order-id
        in: path
        description: The identifier of the order on which operations are being requested on.
        required: true
        schema:
          type: string
          format: uuid
      - name: shipment-id
        in: path
        description: The identifier of the shipment which is being requested.
        required: true
        schema:
          type: string
          format: uuid
      security:
      - merchant_platform:
        - orders/read
      tags:
      - Orders
      responses:
        '200':
          description: Shipment was found and will be returned in the response.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/Shipment'
        '403':
          description: The privileges of the token are insufficient to retrieve orders for this merchant.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/Errors'
        '404':
          description: Merchant order or shipment was not found.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/Errors'
        '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
    patch:
      summary: Update a shipment
      description: Updates a shipment object in preparation for shipping the order. A shipment represents the specific order lines that will be shipped together and plays a central role in the fulfillment process. All shipment fields can be updated except the order line IDs, it is not allowed to add or remove order lines from an existing shipment
      parameters:
      - $ref: '#/components/parameters/Authorization'
      - $ref: '#/components/parameters/x-flow-id'
      - $ref: '#/components/parameters/merchantId'
      - name: order-id
        in: path
        description: The identifier of the order to which the shipment belongs.
        required: true
        schema:
          type: string
          format: uuid
      - name: shipment-id
        in: path
        description: The identifier of the shipment for which updates are being requested.
        required: true
        schema:
          type: string
          format: uuid
      security:
      - merchant_platform:
        - orders/write
      tags:
      - Orders
      requestBody:
        description: The request body contains the updated information of the shipment
        required: true
        content:
          application/vnd.api+json:
            schema:
              type: object
              properties:
                merchant_specified_shipment_id:
                  type: string
                  description: Shipment id used by the partner
                order_lines:
                  type: array
                  items:
                    $ref: '#/components/schemas/ShipmentOrderLine'
                weight:
                  $ref: '#/components/schemas/Weight'
                outbound_logistic_center_id:
                  description: Optional unique identifier of the outbound logistic center.
                  type: string
                  format: uuid
                  example: 57be9d4a-28d6-4b83-94de-b784899cabc9
                tracking_number:
                  type: string
                  example: 003403418039972556
                return_tracking_number:
                  type: string
                  example: ReTurNTracKINGNumBER123461413
                status:
                  $ref: '#/components/schemas/ShipmentStatus'
      responses:
        '204':
          description: Shipment was updated successfully.
          headers:
            Location:
              description: The URL of the patched shipment.
              schema:
                type: string
                format: url
        '400':
          description: Error in the payload - wrong format or missing fields, see error object for more details.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/Errors'
        '403':
          description: The specified update operation (status transition or updating an already 'shipped' shipment) is not allowed or the write permissions are missing for this merchant.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/Errors'
        '404':
          description: Merchant order or shipment was not found.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/Errors'
        '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:
          description: Errors object
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/Errors'
  /merchants/{merchant-id}/orders/{order-id}/items:
    get:
      summary: Retrieves all order items for a given order-id.
      description: Retrieves every order item for the given order-id.
      parameters:
      - $ref: '#/components/parameters/Authorization'
      - $ref: '#/components/parameters/x-flow-id'
      - $ref: '#/components/parameters/merchantId'
      - $ref: '#/components/parameters/itemsInclude'
      - name: order-id
        in: path
        description: The ID of the order for which the items are being requested.
        required: true
        schema:
          type: string
          format: uuid
      security:
      - merchant_platform:
        - orders/read
      tags:
      - Orders
      responses:
        '200':
          description: Order items were found for the given order-id and will be returned.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/OrderItemsTopLevel'
        '403':
          description: The privileges of the token are insufficient to retrieve order items for this merchant.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/Errors'
        '404':
          description: Merchant order was not found.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/Errors'
        '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:
          description: Errors object
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/Errors'
  /merchants/{merchant-id}/orders/{order-id}/items/{order-item-id}:
    get:
      summary: Retrieves an order item with the given identifier.
      description: Retrieves an order item with the given identifier.
      parameters:
      - $ref: '#/components/parameters/Authorization'
      - $ref: '#/components/parameters/x-flow-id'
      - $ref: '#/components/parameters/merchantId'
      - $ref: '#/components/parameters/itemsInclude'
      - name: order-id
        in: path
        description: The identifier of the order for which the items are being requested.
        required: true
        schema:
          type: string
          format: uuid
      - name: order-item-id
        in: path
        description: The identifier of the order item to retrieve.
        required: true
        schema:
          type: string
          format: uuid
      security:
      - merchant_platform:
        - orders/read
      tags:
      - Orders
      responses:
        '200':
          description: Order Item with given identifier was found and will be returned.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/OrderItemTopLevel'
        '403':
          description: The privileges of the token are insufficient to retrieve order for this merchant.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/Errors'
        '404':
          description: Merchant order or item was not found.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/Errors'
        '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:
          description: Errors object
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/Errors'
  /merchants/{merchant-id}/orders/{order-id}/items/{order-item-id}/lines:
    get:
      summary: Retrieves the Order Lines of an order item.
      description: Retrieves the Order Lines of an order item.
      parameters:
      - $ref: '#/components/parameters/Authorization'
      - $ref: '#/components/parameters/x-flow-id'
      - $ref: '#/components/parameters/merchantId'
      - $ref: '#/components/parameters/linesInclude'
      - name: order-id
        in: path
        description: The identifier of the order for which the items are being requested.
        required: true
        schema:
          type: string
          format: uuid
      - name: order-item-id
        in: path
        description: The identifier of the order item to retrieve.
        required: true
        schema:
          type: string
          format: uuid
      security:
      - merchant_platform:
        - orders/read
      tags:
      - Orders
      responses:
        '200':
          description: Order lines were found for the given order item and will be returned.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/OrderLinesTopLevel'
        '403':
          description: The privileges of the token are insufficient to retrieve order information for this merchant.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/Errors'
        '404':
          description: Merchant order, item or line was not found.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/Errors'
        '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:
   

# --- truncated at 32 KB (80 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/zalando/refs/heads/main/openapi/zalando-orders-api-openapi.yml