Zalando stocks API

openapi: 3.2.0
info:
  title: Merchant Stock Service Stocks API
  description: 'The Merchant Stock Service (mStock) API is part of the Article Lifecycle Management and the Zalando Merchant Platform.

    This API provides capabilities to update Stock Quantities per Merchant''s Article in a Sales Channel.

    '
  x-api-id: 8fe636b1-3ac8-4d1b-97b7-51ef41847d70
  x-audience: external-partner
  version: 1.1.0
  contact:
    url: https://developers.merchants.zalando.com/
servers:
- url: api.merchants.zalando.com
  description: Production Environment
- url: api-sandbox.merchants.zalando.com
  description: Sandbox Environment
tags:
- name: stocks
paths:
  /merchants/{merchant-id}/stocks:
    post:
      summary: Update stock quantities for a set of articles.
      tags:
      - stocks
      security:
      - merchant_platform:
        - products/stock/write
      parameters:
      - in: path
        name: merchant-id
        description: The ID of the Merchant.
        schema:
          type: string
          format: uuid
        required: true
      requestBody:
        description: 'The request containing a batch of up to 1000 Stock Updates to process.

          Validation: All Stock Updates in a single batch must have a unique combination of `sales_channel_id` and `ean`.

          '
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StockUpdatesRequest'
      responses:
        207:
          description: 'The requested batch of Stock Updates has been processed. Please consult the response body for the status information of an individual Stock Update.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StockUpdatesResponse'
        default:
          description: Error occurred. See status code and problem object for more information.
          content:
            application/problem+json:
              schema:
                $ref: https://opensource.zalando.com/restful-api-guidelines/problem-1.0.1.yaml#/Problem
components:
  schemas:
    StockUpdatesRequest:
      type: object
      description: The request containing a batch of up to 1000 Stock Updates to process.
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/StockUpdatePerSalesChannel'
          maxItems: 1000
      required:
      - items
    StockUpdatePerSalesChannel:
      type: object
      description: Stock Level for a particular article in a particular Sales Channel.
      properties:
        sales_channel_id:
          type: string
          description: The ID of the Sales Channel.
          format: uuid
        ean:
          type: string
          format: gtin-13
          description: Global Trade Item Number (GTIN-13)
          example: '5901234123457'
        quantity:
          type: integer
          description: The Stock Level for the specified article in the specified Sales Channel.
          format: int32
          minimum: 0
          example: 25
      required:
      - sales_channel_id
      - ean
      - quantity
    StockUpdatesResponse:
      type: object
      description: The response containing results of Stock Updates processing.
      properties:
        results:
          type: array
          items:
            type: object
            properties:
              item:
                $ref: '#/components/schemas/StockUpdatePerSalesChannel'
              result:
                $ref: '#/components/schemas/StockUpdateResult'
            required:
            - item
            - result
      required:
      - results
    ResponseStatus:
      type: string
      x-extensible-enum:
      - ACCEPTED
      - REJECTED
      - FAILED
      description: 'Indicates result of the Product Stock Update.

        - ACCEPTED indicates a successful submission

        - REJECTED indicates validation errors where a detailed description can be found in the `description` field

        - FAILED indicates a failed submission due to internal errors.

        '
      example: ACCEPTED
    ResponseDescription:
      type: string
      description: Detailed error message regarding the status.
    ResponseCode:
      type: integer
      format: int32
      x-extensible-enum:
      - 0
      - 101
      - 102
      - 104
      description: 'Machine readable status code.

        -   0: Update Successful

        - 101: Validation failed

        - 102: Submission failed due to internal errors

        - 104: Update pending - waiting for the article to be onboarded

        '
    StockUpdateResult:
      type: object
      description: The result of Stock Update processing.
      properties:
        status:
          $ref: '#/components/schemas/ResponseStatus'
        code:
          $ref: '#/components/schemas/ResponseCode'
        description:
          $ref: '#/components/schemas/ResponseDescription'
      required:
      - status
      - code
  securitySchemes:
    merchant_platform:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://api.merchants.zalando.com/auth/token
          scopes:
            products/stock/write: Grant write access for stocks to external Merchants.