Zalando Product Association API

openapi: 3.2.0
info:
  version: '1.1'
  title: 'OpenAPI Specification: Products Product Association API'
  description: This specification describes the Products API of the Zalando Merchant Platform.
  x-audience: external-merchant
  x-api-id: 49e51b92-1b36-447f-adb1-be1305faaea6
tags:
- name: Product Association
paths:
  /merchants/{merchant_id}/products/identifiers/{ean}:
    put:
      summary: 'Creates a new simple already known by Zalando by registering the Merchant identifiers in the Zalando system.

        '
      tags:
      - Product Association
      security:
      - OAuth2:
        - lemur.prototype.write
      parameters:
      - $ref: '#/components/parameters/merchant_id'
      - $ref: '#/components/parameters/ean'
      requestBody:
        $ref: '#/components/requestBodies/ProductAssociationBody'
      responses:
        '204':
          description: 'Your sku is successfully associated with the existing product

            '
        '400':
          $ref: '#/components/responses/InvalidBodyError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '409':
          $ref: '#/components/responses/ConflictError'
        '429':
          $ref: '#/components/responses/TooManyRequestsError'
        default:
          $ref: '#/components/responses/GenericError'
components:
  schemas:
    ProductAssociationSchema:
      description: Information of the product to associate with
      type: object
      required:
      - merchant_product_simple_id
      properties:
        merchant_product_simple_id:
          $ref: '#/components/schemas/MerchantProductId'
        merchant_product_config_id:
          $ref: '#/components/schemas/MerchantConfigId'
        merchant_product_model_id:
          $ref: '#/components/schemas/MerchantModelId'
    MerchantProductId:
      description: 'Merchant product simple identifier. Simples is a bottom level tier of a product, contains sizes, metrics, etc.

        '
      type: string
      example: ED-7-09349-5443-L
    EAN:
      description: The International Article Number or also known as European Article Number.
      type: string
      format: gtin13
      example: '9780679762881'
    MerchantConfigId:
      description: 'Merchant product config identifier. Config is a second tier of a product, contains colors, materials, etc.

        '
      type: string
      example: A213-1232SF-SDG62G-213G
    Problem:
      properties:
        type:
          type: string
          format: uri
          description: 'An absolute URI that identifies the problem type. When dereferenced,

            it SHOULD provide human-readable documentation for the problem type

            (e.g., using HTML).

            '
          default: about:blank
        title:
          type: string
          description: 'A short, summary of the problem type. Written in English and readable

            for engineers (usually not suited for non technical stakeholders and

            not localized);

            '
        status:
          type: integer
          format: int32
          description: 'The HTTP status code generated by the origin server for this occurrence

            of the problem.

            '
          minimum: 100
          exclusiveMaximum: 600
        detail:
          type: string
          description: 'A human readable explanation specific to this occurrence of the

            problem.

            '
        instance:
          type: string
          format: uri
          description: 'An absolute URI that identifies the specific occurrence of the problem.

            It may or may not yield further information if dereferenced.

            '
      example:
        type: https://zalando.github.io/problem/constraint-violation
        title: Service Unavailable
        status: 503
        detail: Connection to database timed out
    MerchantModelId:
      description: 'Merchant product model identifier. Model is a top level tier of a product, contains target age groups, brand, size charts, etc.

        '
      type: string
      example: MODEL-ID-ABC
  responses:
    ForbiddenError:
      description: Accessing the data you were trying to reach is forbidden
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    ConflictError:
      description: The request is semantically correct, but it cannot be processed due to business reasons. e.g. A product with same id was already submitted. Please refer to the response.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    InvalidBodyError:
      description: No product with the given EAN could be found for this merchant
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    GenericError:
      description: Error occurred - see status code and problem object for more information.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    NotFoundError:
      description: No product with the given EAN could be found for this merchant
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    TooManyRequestsError:
      description: Too Many Requests. Server busy, please retry later.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
  requestBodies:
    ProductAssociationBody:
      description: Information of the product to associate with
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ProductAssociationSchema'
  parameters:
    ean:
      name: ean
      in: path
      description: The International Article Number or also known as European Article Number.
      required: true
      schema:
        $ref: '#/components/schemas/EAN'
    merchant_id:
      name: merchant_id
      in: path
      description: Id of the merchant
      required: true
      schema:
        type: string
        format: string
  securitySchemes:
    merchant_platform:
      type: oauth2
      description: The Products service uses the OpenID Connect (OIDC) authentication layer of OAuth 2 to handle the client credentials process flow.
      flows:
        clientCredentials:
          tokenUrl: https://api-sandbox.merchants.zalando.com/auth/token
          scopes:
            products/read: scope to read a product
            products/write: scope to create or update a product