Zalando offer-blockers API

openapi: 3.0.2
info:
  title: Article Requirements AnnouncedReturns offer-blockers 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: offer-blockers
paths:
  /merchants/{merchant-id}/offer-blockers:
    post:
      summary: Create Offer Blockers.
      description: 'This is a batch endpoint. Creation results for each requested Offer Blocker will be reported separately.

        Created Offer Blockers will be enriched with an ID.


        If there is already an Offer Blocker with exactly the same criteria and reason, then no new Offer Blocker

        will be created and the ID of the existing one will be returned in response.


        If batch contains multiple Offer Blockers with exactly the same criteria and reason, such Offer Blockers will

        be rejected.

        '
      tags:
      - offer-blockers
      security:
      - merchant_platform:
        - products/blockers/write
      parameters:
      - in: path
        name: merchant-id
        schema:
          $ref: '#/components/schemas/MerchantId'
        required: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOfferBlockersRequest'
      responses:
        207:
          description: Request was processed successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateOfferBlockersResponse'
        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
    get:
      summary: List Offer Blockers.
      tags:
      - offer-blockers
      security:
      - merchant_platform:
        - products/blockers/read
      parameters:
      - in: path
        name: merchant-id
        schema:
          $ref: '#/components/schemas/MerchantId'
        required: true
      - in: query
        name: ean
        schema:
          $ref: '#/components/schemas/Ean'
        required: false
      - in: query
        name: sales_channel_id
        schema:
          $ref: '#/components/schemas/SalesChannelId'
        required: false
      - in: query
        name: updated_since
        schema:
          $ref: '#/components/schemas/UpdatedSince'
        required: false
      - in: query
        name: updated_until
        schema:
          $ref: '#/components/schemas/UpdatedUntil'
        required: false
      - in: query
        name: cursor
        schema:
          $ref: '#/components/schemas/Cursor'
        required: false
      - in: query
        name: page_size
        schema:
          $ref: '#/components/schemas/PageSize'
        required: false
      responses:
        200:
          description: Request was processed successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListOfferBlockersResponse'
        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
    delete:
      summary: Delete Offer Blockers.
      description: 'This is a batch endpoint. Deletion results for each Offer Blocker will be reported separately.


        Offer Blockers that were successfully deleted, will be reported back with status "ACCEPTED" in the response.

        '
      tags:
      - offer-blockers
      security:
      - merchant_platform:
        - products/blockers/write
      parameters:
      - in: path
        name: merchant-id
        schema:
          $ref: '#/components/schemas/MerchantId'
        required: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeleteOfferBlockersRequest'
      responses:
        207:
          description: Request was processed successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteOfferBlockersResponse'
        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
  /merchants/{merchant-id}/offer-blockers/{offer-blocker-id}:
    get:
      summary: Get details about an Offer Blocker.
      tags:
      - offer-blockers
      security:
      - merchant_platform:
        - products/blockers/read
      parameters:
      - in: path
        name: merchant-id
        schema:
          $ref: '#/components/schemas/MerchantId'
        required: true
      - in: path
        name: offer-blocker-id
        schema:
          $ref: '#/components/schemas/OfferBlockerId'
        required: true
      responses:
        200:
          description: Offer Blocker was found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OfferBlocker'
        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:
    Cursor:
      type: string
      format: byte
      example: ewpsYXN0OiAyNTkKb3JkZXI6IGFzYwp9
      description: 'A value indicating that there are more results than could be returned immediately.

        Pass it in the next request to get the next batch of results.

        If there is no cursor in the response, it means that there are no more results left.

        '
    NewProductBlocker:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/NewOfferBlockerId'
        reason:
          $ref: '#/components/schemas/OfferBlockerReason'
        description:
          $ref: '#/components/schemas/OfferBlockerDescription'
        criteria:
          $ref: '#/components/schemas/ProductOfferBlockerCriteria'
      required:
      - reason
      - criteria
    Cursors:
      type: object
      properties:
        self:
          $ref: '#/components/schemas/CursorUrl'
        next:
          $ref: '#/components/schemas/CursorUrl'
      required:
      - self
      description: 'There are three cursor directions available:

        - self: returns the current batch

        - prev: returns the previous batch

        - next: returns the next batch

        '
    CursorUrl:
      type: string
      format: uri
      example: https://api-sandbox.merchants.com/merchants/e2ad171a-6b52-4db0-8ae3-54709720458b/offer-blockers?cursor=ewpsYXN0OiAyNTkKb3JkZXI6IGFzYwp9
      description: The location where you can find the next selected batch of Offer Blockers.
    CreateOfferBlockersRequest:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/NewProductBlocker'
          maxItems: 5
      required:
      - items
    NewOfferBlocker:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/NewOfferBlockerId'
        reason:
          $ref: '#/components/schemas/OfferBlockerReason'
        description:
          $ref: '#/components/schemas/OfferBlockerDescription'
        criteria:
          $ref: '#/components/schemas/OfferBlockerCriteria'
      required:
      - reason
      - criteria
    OfferBlocker:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/OfferBlockerId'
        reason:
          $ref: '#/components/schemas/OfferBlockerReason'
        description:
          $ref: '#/components/schemas/OfferBlockerDescription'
        criteria:
          $ref: '#/components/schemas/OfferBlockerCriteria'
      required:
      - id
      - reason
      - criteria
    OfferBlockerCriteria:
      description: 'Criteria describing which articles are blocked by this Offer Blocker.

        Any combination of conditions can be provided. They are combined using logical "AND".

        If no conditions are provided, this means "all articles".

        '
      type: object
      properties:
        sales_channel_id:
          $ref: '#/components/schemas/SalesChannelId'
        ean:
          $ref: '#/components/schemas/Ean'
    ProductOfferBlockerCriteria:
      description: 'Criteria describing which articles are blocked by this Offer Blocker.

        The EAN is required. Criteria are combined using logical "AND".

        '
      type: object
      properties:
        sales_channel_id:
          $ref: '#/components/schemas/SalesChannelId'
        ean:
          $ref: '#/components/schemas/Ean'
      required:
      - ean
      - sales_channel_id
    UpdatedSince:
      type: string
      format: date-time
      example: '2020-05-30T00:00:00.00Z'
      description: 'If set, the response will only contain Offer Blockers which were created or updated after this time.

        The date-time format is defined as in RFC 3339, section 5.6.

        '
    OfferBlockerId:
      description: The ID of the Offer Blocker.
      type: string
      format: uuid
    SalesChannelId:
      description: The ID of the Sales Channel.
      type: string
      format: uuid
    ListOfferBlockersResponse:
      type: object
      properties:
        cursors:
          $ref: '#/components/schemas/Cursors'
        query:
          $ref: '#/components/schemas/ListOfferBlockersQuery'
        items:
          type: array
          items:
            $ref: '#/components/schemas/OfferBlocker'
      required:
      - query
      - items
      - cursors
    CreateOfferBlockersResponse:
      type: object
      properties:
        results:
          type: array
          items:
            type: object
            properties:
              item:
                $ref: '#/components/schemas/NewOfferBlocker'
              result:
                $ref: '#/components/schemas/OfferBlockerResult'
            required:
            - item
            - result
      required:
      - results
    PageSize:
      type: integer
      minimum: 1
      example: 10
      default: 100
      description: 'A positive value indicating how many results should be returned for one request.

        '
    OfferBlockerDescription:
      description: "Human-readable description explaining why this blocker exists. \nYou can include any identifier in the description to distinguish the blocker source \n(e.g., system name, id, process identifier).\n"
      type: string
    ListOfferBlockersQuery:
      description: 'Object containing the query filters applied in the search request to filter Offer Blockers.

        '
      type: object
      properties:
        ean:
          $ref: '#/components/schemas/Ean'
        sales_channel_id:
          $ref: '#/components/schemas/SalesChannelId'
        updated_since:
          $ref: '#/components/schemas/UpdatedSince'
        updated_until:
          $ref: '#/components/schemas/UpdatedUntil'
        page_size:
          $ref: '#/components/schemas/PageSize'
    DeleteOfferBlockersRequest:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/OfferBlockerId'
          maxItems: 5
      required:
      - items
    DeleteOfferBlockersResponse:
      type: object
      properties:
        results:
          type: array
          items:
            type: object
            properties:
              item:
                $ref: '#/components/schemas/OfferBlockerId'
              result:
                $ref: '#/components/schemas/OfferBlockerResult'
            required:
            - item
            - result
      required:
      - results
    MerchantId:
      description: The ID of the Merchant.
      type: string
      format: uuid
    OfferBlockerReason:
      type: string
      enum:
      - PAUSE_01
      - PAUSE_02
      - PAUSE_03
      - PAUSE_04
      - PAUSE_05
      - PAUSE_06
      - PABLO_01
      - PABLO_02
      - PABLO_03
      - PABLO_04
      description: "Indicates result of the Offer Blocker request.\n- PAUSE_01: End of season/removal from assortment\n- PAUSE_02: High return rate     \n- PAUSE_03: Stock issue Low sales performance\n- PAUSE_04: Quality issues  \n- PAUSE_05: Legal issues\n- PAUSE_06: Other reasons\n- PABLO_01: Generic issue (PABLO codes will be deprecated in the future)\n- PABLO_02: Price issue (PABLO codes will be deprecated in the future)\n- PABLO_03: Stock issue (PABLO codes will be deprecated in the future)\n- PABLO_04: Product launch (PABLO codes will be deprecated in the future)\n"
      example: PAUSE_01
    NewOfferBlockerId:
      description: The ID of the newly-created Offer Blocker.
      type: string
      format: uuid
      readOnly: true
    ResponseDescription:
      type: string
      description: Detailed message regarding the request status.
    ResponseStatus:
      type: string
      enum:
      - ACCEPTED
      - REJECTED
      - FAILED
      description: 'Indicates result of the Offer Blocker request.

        - ACCEPTED: indicates a successful request.

        - 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
    OfferBlockerResult:
      type: object
      description: The result of processing an Offer Blocker request.
      properties:
        status:
          $ref: '#/components/schemas/ResponseStatus'
        description:
          $ref: '#/components/schemas/ResponseDescription'
      required:
      - status
    Ean:
      description: Global Trade Item Number (GTIN-13).
      type: string
      format: gtin-13
      example: '5901234123457'
    UpdatedUntil:
      type: string
      format: date-time
      example: '2020-05-30T00:00:00.00Z'
      description: 'If set, the response will only contain Offer Blockers which were created or updated before this time.

        The date-time format is defined as in RFC 3339, section 5.6.

        '