openapi: 3.0.1
info:
  title: Subscriptions API
  description: | 
    The Subscriptions API is designed to cater to the needs of retailers by providing comprehensive solutions for managing event notification subscriptions. This API enables retailers to efficiently track and respond to various event notifications, ensuring seamless operational workflows and enhanced communication channels.
  termsOfService: https://api.bol.com/retailer/public/Retailer-API/legal/terms-of-service.html
  contact:
    name: developers.bol.com
    url: https://developers.bol.com
  version: 11.1.4
  x-logo:
    url: https://api.bol.com/retailer/public/Retailer-API/_images/bolcom_logo.png
    altText: bol.com logo
security:
  - OAuth2: [ ]
tags:
  - name: "Management"
    description: "Endpoints dedicated to managing subscriptions, including functionalities to create, read, update, and delete records."
  - name: "Query"
    description: "Endpoints designed for querying subscriptions and signature keys, enabling the retrieval of records based on specified path or query parameters."

paths:
  /retailer/subscriptions:
    get:
      summary: Retrieve All Retailer Event Notification Subscriptions
      description: "This endpoint allows retailers to fetch a comprehensive list of all their event notification subscriptions. Each subscription includes details about event types and destinations, which can vary between URLs (for WEBHOOK type) or topic names (for GCP_PUBSUB type). It's an essential tool for retailers to keep track of their notifications and customize their responses accordingly."
      operationId: get-push-notification-subscriptions
      x-bol-scopes:
        - retailer
        - subscriptions.read
        - subscriptions.manage
      tags:
        - Query
      responses:
        "200":
          $ref: "#/components/responses/200_GET_LIST"
        "400":
          $ref: '../common/responses.yaml#/components/responses/400_BAD_REQUEST'
        "403":
          $ref: '../common/responses.yaml#/components/responses/403_FORBIDDEN'
        "404":
          $ref: '../common/responses.yaml#/components/responses/404_NOT_FOUND'
        "409":
          $ref: '../common/responses.yaml#/components/responses/409_CONFLICT'
        "500":
          $ref: '../common/responses.yaml#/components/responses/500_INTERNAL_SERVER_ERROR'
        "503":
          $ref: '../common/responses.yaml#/components/responses/503_SERVICE_UNAVAILABLE'
        "504":
          $ref: '../common/responses.yaml#/components/responses/504_GATEWAY_TIMEOUT'
    post:
      summary: Create a New Event Notification Subscription
      description: "This endpoint is used to establish a new event notification subscription tailored to a retailer's requirements. Retailers can specify the types of events they wish to subscribe to and designate the appropriate destination for notifications, ensuring they receive timely updates in their preferred format."
      operationId: post-push-notification-subscription
      x-bol-scopes:
        - retailer
        - subscriptions.manage
      tags:
        - Management
      requestBody:
        description: "The request body contains details for creating a new event notification subscription. Retailers must specify the types of events they are interested in and the corresponding notification destination."
        content:
          application/vnd.subscriptions.v11+json:
            schema:
              $ref: '#/components/schemas/SubscriptionRequest'
        required: true
      responses:
        "204":
          description: Subscription was created successfully.
          content:
            application/vnd.subscriptions.v11+json: { }
        "400":
          $ref: '../common/responses.yaml#/components/responses/400_BAD_REQUEST'
        "403":
          $ref: '../common/responses.yaml#/components/responses/403_FORBIDDEN'
        "409":
          $ref: '../common/responses.yaml#/components/responses/409_CONFLICT'
        "500":
          $ref: '../common/responses.yaml#/components/responses/500_INTERNAL_SERVER_ERROR'
        "503":
          $ref: '../common/responses.yaml#/components/responses/503_SERVICE_UNAVAILABLE'
        "504":
          $ref: '../common/responses.yaml#/components/responses/504_GATEWAY_TIMEOUT'
  /retailer/subscriptions/{subscription-id}:
    get:
      summary: Fetch Details of a Specific Event Notification Subscription
      description: "This endpoint provides detailed information about a specific event notification subscription associated with a retailer. By utilizing the unique subscription ID, retailers can access in-depth details of their subscriptions, including event types and notification destinations."
      operationId: get-push-notification-subscription
      x-bol-scopes:
        - retailer
        - subscriptions.read
        - subscriptions.manage
      tags:
        - Query
      parameters:
      - name: subscription-id
        in: path
        required: true
        schema:
          $ref: '../common/models.yaml#/components/schemas/subscriptionId'
      responses:
        "200":
          $ref: "#/components/responses/200_GET_SINGLE"
        "400":
          $ref: '../common/responses.yaml#/components/responses/400_BAD_REQUEST'
        "403":
          $ref: '../common/responses.yaml#/components/responses/403_FORBIDDEN'
        "404":
          $ref: '../common/responses.yaml#/components/responses/404_NOT_FOUND'
        "409":
          $ref: '../common/responses.yaml#/components/responses/409_CONFLICT'
        "500":
          $ref: '../common/responses.yaml#/components/responses/500_INTERNAL_SERVER_ERROR'
        "503":
          $ref: '../common/responses.yaml#/components/responses/503_SERVICE_UNAVAILABLE'
        "504":
          $ref: '../common/responses.yaml#/components/responses/504_GATEWAY_TIMEOUT'
    put:
      tags:
      - Management
      summary: Update an Existing Event Notification Subscription
      description: "Retailers can use this endpoint to modify the details of an existing event notification subscription. This includes changing the event types they are subscribed to, as well as updating the notification destination to align with evolving business needs."
      operationId: put-push-notification-subscription
      x-bol-scopes:
        - retailer
        - subscriptions.manage
      parameters:
      - name: subscription-id
        in: path
        required: true
        schema:
          $ref: '../common/models.yaml#/components/schemas/subscriptionId'
      requestBody:
        description: The request body contains updated information for modifying an existing event notification subscription. Retailers must specify any changes to the event types or notification destinations.
        content:
          application/vnd.subscriptions.v11+json:
            schema:
              $ref: '#/components/schemas/SubscriptionRequest'
        required: true
      responses:
        "204":
          description: Subscription was updated successfully.
          content:
            application/vnd.subscriptions.v11+json: { }
        "400":
          $ref: '../common/responses.yaml#/components/responses/400_BAD_REQUEST'
        "403":
          $ref: '../common/responses.yaml#/components/responses/403_FORBIDDEN'
        "404":
          $ref: '../common/responses.yaml#/components/responses/404_NOT_FOUND'
        "409":
          $ref: '../common/responses.yaml#/components/responses/409_CONFLICT'
        "500":
          $ref: '../common/responses.yaml#/components/responses/500_INTERNAL_SERVER_ERROR'
        "503":
          $ref: '../common/responses.yaml#/components/responses/503_SERVICE_UNAVAILABLE'
        "504":
          $ref: '../common/responses.yaml#/components/responses/504_GATEWAY_TIMEOUT'
    delete:
      tags:
      - Management
      summary: Remove a Specific Event Notification Subscription
      description: "This endpoint is intended for retailers who wish to discontinue a particular event notification subscription. By providing the subscription ID, they can effectively remove the subscription from their profile, ceasing the associated notifications."
      operationId: delete-push-notification-subscription
      x-bol-scopes:
        - retailer
        - subscriptions.manage
      parameters:
      - name: subscription-id
        in: path
        required: true
        schema:
          $ref: '../common/models.yaml#/components/schemas/subscriptionId'
      responses:
        "204":
          description: Subscription was deleted successfully.
          content:
            application/vnd.subscriptions.v11+json: { }
        "400":
          $ref: '../common/responses.yaml#/components/responses/400_BAD_REQUEST'
        "403":
          $ref: '../common/responses.yaml#/components/responses/403_FORBIDDEN'
        "404":
          $ref: '../common/responses.yaml#/components/responses/404_NOT_FOUND'
        "409":
          $ref: '../common/responses.yaml#/components/responses/409_CONFLICT'
        "500":
          $ref: '../common/responses.yaml#/components/responses/500_INTERNAL_SERVER_ERROR'
        "503":
          $ref: '../common/responses.yaml#/components/responses/503_SERVICE_UNAVAILABLE'
        "504":
          $ref: '../common/responses.yaml#/components/responses/504_GATEWAY_TIMEOUT'
  /retailer/subscriptions/signature-keys:
    get:
      tags:
      - Query
      summary: Retrieve Public Keys for Signature Verification
      description: This endpoint offers a list of public keys which are essential for validating the signature header of push notifications received from bol.com. It's a crucial feature for ensuring the authenticity and integrity of the received notifications.
      operationId: get-subscription-keys
      x-bol-scopes:
        - retailer
        - subscriptions.read
        - subscriptions.manage
      responses:
        "200":
          $ref: "#/components/responses/200_GET_SIGNATURES"
        "400":
          $ref: '../common/responses.yaml#/components/responses/400_BAD_REQUEST'
        "403":
          $ref: '../common/responses.yaml#/components/responses/403_FORBIDDEN'
        "409":
          $ref: '../common/responses.yaml#/components/responses/409_CONFLICT'
        "500":
          $ref: '../common/responses.yaml#/components/responses/500_INTERNAL_SERVER_ERROR'
        "503":
          $ref: '../common/responses.yaml#/components/responses/503_SERVICE_UNAVAILABLE'
        "504":
          $ref: '../common/responses.yaml#/components/responses/504_GATEWAY_TIMEOUT'
  /retailer/subscriptions/test/{subscription-id}:
    post:
      tags:
      - Management
      summary: Send Test Notification for a Subscription
      description: "This endpoint allows retailers to send a test push notification to verify the functionality of their subscriptions. It's an essential tool for ensuring that the event notification system is set up correctly and functioning as expected."
      operationId: post-test-push-notification
      x-bol-scopes:
        - retailer
        - subscriptions.manage
      parameters:
      - name: subscription-id
        in: path
        description: The unique identifier assigned to each event notification subscription. This ID is used for tracking and managing each subscription.
        required: true
        schema:
          $ref: '../common/models.yaml#/components/schemas/subscriptionId'
      responses:
        "201":
          description: "The request was successful, and a test push notification has been triggered. The response includes a unique reference for tracking the notification."
          content:
            application/vnd.subscriptions.v11+json:
              schema:
                $ref: "#/components/schemas/TestNotificationResponse"
        "400":
          $ref: '../common/responses.yaml#/components/responses/400_BAD_REQUEST'
        "403":
          $ref: '../common/responses.yaml#/components/responses/403_FORBIDDEN'
        "404":
          $ref: '../common/responses.yaml#/components/responses/404_NOT_FOUND'
        "409":
          $ref: '../common/responses.yaml#/components/responses/409_CONFLICT'
        "500":
          $ref: '../common/responses.yaml#/components/responses/500_INTERNAL_SERVER_ERROR'
        "503":
          $ref: '../common/responses.yaml#/components/responses/503_SERVICE_UNAVAILABLE'
        "504":
          $ref: '../common/responses.yaml#/components/responses/504_GATEWAY_TIMEOUT'
components:
  responses:
    "200_GET_LIST":
      description: "The request was successful, and the list of subscriptions have been retrieved successfully."
      content:
        application/vnd.subscriptions.v11+json:
          schema:
            $ref: "#/components/schemas/SubscriptionsResponse"
    "200_GET_SINGLE":
      description: "The request was successful, and the list of subscriptions have been retrieved successfully."
      content:
        application/vnd.subscriptions.v11+json:
          schema:
            $ref: "#/components/schemas/SubscriptionResponse"
    "200_GET_SIGNATURES":
      description: "The request was successful, and the list of subscriptions have been retrieved successfully."
      content:
        application/vnd.subscriptions.v11+json:
          schema:
            $ref: "#/components/schemas/KeySets"
  schemas:
    TestNotificationResponse:
      required:
        - resourceId
        - resource
        - type
      type: object
      properties:
        resourceId:
          type: string
          description: "A unique reference assigned to the test push notification. This reference correlates to the push notification received (resource_id), facilitating easier tracking and verification of the notification delivery."
          example: "0c6573a2-a80c-48b7-a03e-d5939f1173fa"
        resource:
          type: string
          description: "This is the resource type that the event relates to. "
          example: TEST
        type:
          type: string
          description: "The specific action or outcome that occurred for the resource."
          example: NEW
      description: "The response structure for a test push notification request, containing a unique reference for tracking purposes."
    SubscriptionRequest:
      required:
      - resources
      - subscriptionType
      - eventDestination
      type: object
      properties:
        resources:
          $ref: '#/components/schemas/resources'
        eventDestination:
          $ref: '#/components/schemas/eventDestination'
        subscriptionType:
          $ref: '#/components/schemas/subscriptionType'
        enabled:
          $ref: '#/components/schemas/enabled'
        identity:
          $ref: '#/components/schemas/identity'
      description: "The subscription request structure, encompassing resources, subscription type, and notification URL."
    SubscriptionsResponse:
      required:
      - subscriptions
      type: object
      properties:
        subscriptions:
          type: array
          items:
            $ref: '#/components/schemas/SubscriptionResponse'
      description: Provides a comprehensive list of subscriptions in response to queries.
    SubscriptionResponse:
      required:
      - id
      - resources
      - subscriptionType
      - eventDestination
      type: object
      properties:
        id:
          $ref: '../common/models.yaml#/components/schemas/subscriptionId'
        resources:
          $ref: '#/components/schemas/resources'
        eventDestination:
          $ref: '#/components/schemas/eventDestination'
        subscriptionType:
          $ref: '#/components/schemas/subscriptionType'
        enabled:
          $ref: '#/components/schemas/enabled'
        identity:
          $ref: '#/components/schemas/identity'
      description: "The response structure for a subscription, including all necessary details."
    resources:
      type: array
      items:
        type: string
        description: "Defines the specific event types the subscription is configured to listen to. Each item in the array corresponds to a predefined event category that triggers notifications. "
        enum:
          - TEST
          - PROCESS_STATUS
          - SHIPMENT
          - PRICE_STAR_BOUNDARY
          - COMPETING_OFFER
          - OFFER_FOR_SALE
          - OFFER_NOT_FOR_SALE
          - ORDER
    eventDestination:
      type: string
      description: "The destination for event notifications. For WEBHOOK subscription types, this is the URL where messages are posted to. For GCP_PUBSUB, this is the topic name."
      example: https://www.bol.com/webhook
    subscriptionType:
      type: string
      description: "Defines the platform (WEBHOOK, GCP_PUBSUB, or AWS_SQS) for event subscriptions, with certain event types exclusive to specific platforms. This field enables retailers to align their subscription type with their technological setup and notification handling preferences."
      example: WEBHOOK
      enum:
        - WEBHOOK
        - GCP_PUBSUB
        - AWS_SQS
    enabled:
      type: boolean
      description: Whether the subscription is enabled and will receive notifications or not. Defaults to true.
      example: true
    identity:
      type: string
      description: Identity needed for publishing a notification. Must be provided if subscriptionType = AWS_SQS and must be in format of AWS ARN.
      example: 'arn:aws:iam::<numeric AWS account id>:role/<role name>'
    KeySets:
      required:
        - signatureKeys
      type: object
      properties:
        signatureKeys:
          type: array
          items:
            $ref: '#/components/schemas/keySet'
    keySet:
      required:
        - id
        - publicKey
        - type
      type: object
      description: "Defines the structure for each key set, including ID, public key, and type."
      properties:
        id:
          type: string
          description: "A unique identifier for each key in the key set, essential for distinguishing and referencing specific keys within the set."
          example: "1"
        type:
          type: string
          description: "Specifies the encryption type of the key, such as RSA, crucial for understanding the security mechanism and compatibility with cryptographic processes."
          example: RSA
          enum:
            - RSA
        publicKey:
          type: string
          description: "The Base64 encoded public key, used for verifying signatures in push notifications, ensuring the authenticity and integrity of the messages received."
          example: "MIIEvAIBADANBgkqhkiG9w0BAQEFAASCBKYwggSiAgEAAoIBAQCDO7X3OGEqB6LU2ZQdznuYJX1KhCiJUB0+IwW9UjcgbU2Y/LzUIgGPT33s/+OqqMQOtXp2RV4JM6Zv5/YUZgZAqEIkvvrIYvJB8tXv73VQS2r4Ssy3Y/frJsqy8a3sDOoFeJygHYE6kVf3sOCdo4CO6PFUe7ZwsOSS2/7fNWAaMhY6tEuZwkA7ZLoSd3UHTdeKlV1TH5I3yFClMo1FwABsWzj9DhvEb6Q36j+QLJZAj0xvusJUsOjcSgyXRzVBFtwwNILzs9BO+GWRI4li+rjhaST2pNtvGfnQB5TUOO7Yegk/ucSiV1cFzy95gWQV2F0c9P1vBctETrYKxQBklBbjAgMBAAECggEAGISLVoi9/nA2x7VuqrLs/FvksItIV38UN4urgtddXT2OhcqSLL+9styTFjgofLXTCzx0iKwlCWsQ6U9Y9i6pdGL7GIplqBJ0WEXaGl2OeVXdwk2XOZv/sXsp24yzhapT/nmuKWvZvOtyl9/1vO5DPoQPExwpVUnHxji4SjDr6DuKVNDwh9Z4mVsdfdYVeLYGJ356IGWhTu/JDie4byl8B75UgbmyvfJRjQkoLpVZuhu+jkmhogpoSl6NtaKA+iFlGT9JLtGVHDn15kdEHb+dtzTzyJH40KGjQ7OiZcmA8GFft6zrNlOpyziH7fICtt0/7fR348/Z+XIYUFqfadQQKBgQDeVnqAlkt2Uab/1OjX9O8CRWqdoFLpUGDiHhkaXEylJtm1osFHGiyOi1eEQOy/lnJWKUp7c0b8D/QioP7kI38ES1mBx1KDzFgob4p/U+4R+z24SV/Q3CT6vHbfbe1XxWvE4SOdh4p7+Kuhxz1n6P0TWltvsTbpCJ9GM4wi2Z26QKBgQCXGiObkJI4Wv6RGxq76BHEDZdrLWppXh1+FYfyUaq6bfcSF86yAIRlleEJUh1v10KDw2DCX0rhO3BW0juEl5qz5RohLIxuak+2RbX6IQrVPwtCCeGQzKIRPktht+fi+eSaa5XNMLXURTzjVUdxzFwqDKp+7YQWL8DJ6qEfJGGYX6wKBgBXM8PIOypNtaiyHmdUjBRR57fxKrhaGdRl2zgtRpYpEBvDSZpUsMdZAP3KOUyh4LiGZ+Yfk80mcAwXVrx9Ji0J+BK+OXwbV+od5FIZVei2dj9SdOuoBmNZIITLeXtb/3cZu6X52gnqmNNncEbDb2F2qAX5rSC4pJ+CQQBduc7uRAoGAHzjxfqWi8S4sSAOXxJgxg5djYGwj/t3JrlH4o2OoqZkrYnu05CcjNHKB65EiKq3sM5gYgmayWukzOvoDH/fIakHey9fXTluezVwYt0NBf9e7ihoiakfG/0JSonbypTkXdw5OgsEp3YfHMJ0XtlhefbgDBY8IvF/HrnyzSKRYBD0CgYBlq6nIEZOIqngHdtskT8JOZBcniVPGjUjSiNcYQXfeMwKINUqDGC/YmpPgBOhO93ozeQTCBeeMD8nlbkTHPu7BxCCfpKj6/PPMfxmyFQyDg9ZjjHOIhUMddRw+mSq0zS212JbIr3O4eEtrXPqWfq5phxyE3dRvaX3A3wiEQN9WRA=="