Bol Subscriptions API

openapi: 3.2.0
info:
  title: v10 - Retailer Subscriptions API
  description: 'The bol.com API for retailers.


    # Authentication

    Our API requires authentication via OAuth2. The detailed steps to authenticate are explained here


    # Demo scenarios

    Our API specification includes examples of the responses you can expect. For more information as well as more examples, we refer you to the following resources:

    - Demo environment

    - Demo scenarios'
  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: 10.x
  x-logo:
    url: https://api.bol.com/retailer/public/Retailer-API/_images/bolcom_logo.png
    altText: bol.com logo
security:
- OAuth2: []
tags:
- name: Subscriptions
  description: Push notification subscriptions resource
paths:
  /retailer/subscriptions:
    get:
      tags:
      - Subscriptions
      summary: Retrieve Event Notification Subscriptions
      description: Retrieves all event notification subscriptions for a given retailer. Each subscription may have different types of events and a destination, which could either be a URL (for WEBHOOK) or a topic name (for GCP_PUBSUB).
      operationId: get-push-notification-subscriptions
      responses:
        '200':
          description: 'Ok: Successfully processed the request.'
          content:
            application/vnd.retailer.v10+json:
              schema:
                $ref: '#/components/schemas/SubscriptionsResponse'
        '400':
          description: 'Bad request: The sent request does not meet the API specification. Please check the error message(s) for more information.'
          content:
            application/vnd.retailer.v10+json:
              schema:
                $ref: '#/components/schemas/Problem'
      deprecated: true
      x-badges:
      - name: DEPRECATED
        position: after
        color: '#f10000'
    post:
      tags:
      - Subscriptions
      summary: Create Event Notification Subscription
      description: Creates a new event notification subscription for a retailer. The subscription can be set up for one or more types of events and the destination can either be a URL (for WEBHOOK) or a topic name (for GCP_PUBSUB).
      operationId: post-push-notification-subscription
      requestBody:
        content:
          application/vnd.retailer.v10+json:
            schema:
              $ref: '#/components/schemas/SubscriptionRequest'
        required: true
      responses:
        '202':
          description: 'Accepted: Successfully scheduled the request for processing.'
          content:
            application/vnd.retailer.v10+json:
              schema:
                $ref: '#/components/schemas/ProcessStatus'
        '400':
          description: 'Bad request: The sent request does not meet the API specification. Please check the error message(s) for more information.'
          content:
            application/vnd.retailer.v10+json:
              schema:
                $ref: '#/components/schemas/Problem'
      deprecated: true
      x-badges:
      - name: DEPRECATED
        position: after
        color: '#f10000'
  /retailer/subscriptions/signature-keys:
    get:
      tags:
      - Subscriptions
      summary: Retrieve public keys for push notification signature validation
      description: Retrieve a list of public keys that should be used to validate the signature header for push notifications received from bol.com.
      operationId: get-subscription-keys
      responses:
        '200':
          description: 'Ok: Successfully processed the request.'
          content:
            application/vnd.retailer.v10+json:
              schema:
                $ref: '#/components/schemas/KeySetResponse'
      deprecated: true
      x-badges:
      - name: DEPRECATED
        position: after
        color: '#f10000'
  /retailer/subscriptions/test/{subscription-id}:
    post:
      tags:
      - Subscriptions
      summary: Send test push notification for subscriptions
      description: Send a test push notification to all subscriptions for the provided event.
      operationId: post-test-push-notification
      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:
          type: string
        example: 1234
      responses:
        '202':
          description: 'Accepted: Successfully scheduled the request for processing.'
          content:
            application/vnd.retailer.v10+json:
              schema:
                $ref: '#/components/schemas/ProcessStatus'
        '400':
          description: 'Bad request: The sent request does not meet the API specification. Please check the error message(s) for more information.'
          content:
            application/vnd.retailer.v10+json:
              schema:
                $ref: '#/components/schemas/Problem'
      deprecated: true
      x-badges:
      - name: DEPRECATED
        position: after
        color: '#f10000'
  /retailer/subscriptions/{subscription-id}:
    get:
      tags:
      - Subscriptions
      summary: Retrieve Specific Event Notification Subscription
      description: Fetches the details of a specific event notification subscription for a retailer. The details include the types of events and the destination, which can either be a URL (for WEBHOOK) or a topic name (for GCP_PUBSUB).
      operationId: get-push-notification-subscription
      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:
          type: string
        example: 1234
      responses:
        '200':
          description: 'Ok: Successfully processed the request.'
          content:
            application/vnd.retailer.v10+json:
              schema:
                $ref: '#/components/schemas/SubscriptionResponse'
        '404':
          description: 'Not found: The requested item could not be found.'
          content:
            application/vnd.retailer.v10+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '400':
          description: 'Bad request: The sent request does not meet the API specification. Please check the error message(s) for more information.'
          content:
            application/vnd.retailer.v10+json:
              schema:
                $ref: '#/components/schemas/Problem'
      deprecated: true
      x-badges:
      - name: DEPRECATED
        position: after
        color: '#f10000'
    put:
      tags:
      - Subscriptions
      summary: Update Event Notification Subscription
      description: Updates the details of a specific event notification subscription for a retailer. The updates can be made to the types of events and/or the destination, which can either be a URL (for WEBHOOK) or a topic name (for GCP_PUBSUB).
      operationId: put-push-notification-subscription
      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:
          type: string
        example: 1234
      requestBody:
        content:
          application/vnd.retailer.v10+json:
            schema:
              $ref: '#/components/schemas/SubscriptionRequest'
        required: true
      responses:
        '202':
          description: 'Accepted: Successfully scheduled the request for processing.'
          content:
            application/vnd.retailer.v10+json:
              schema:
                $ref: '#/components/schemas/ProcessStatus'
        '400':
          description: 'Bad request: The sent request does not meet the API specification. Please check the error message(s) for more information.'
          content:
            application/vnd.retailer.v10+json:
              schema:
                $ref: '#/components/schemas/Problem'
      deprecated: true
      x-badges:
      - name: DEPRECATED
        position: after
        color: '#f10000'
    delete:
      tags:
      - Subscriptions
      summary: Remove Event Notification Subscription
      description: Deletes a specific event notification subscription associated with a retailer.
      operationId: delete-push-notification-subscription
      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:
          type: string
        example: 1234
      responses:
        '202':
          description: 'Accepted: Successfully scheduled the request for processing.'
          content:
            application/vnd.retailer.v10+json:
              schema:
                $ref: '#/components/schemas/ProcessStatus'
        '400':
          description: 'Bad request: The sent request does not meet the API specification. Please check the error message(s) for more information.'
          content:
            application/vnd.retailer.v10+json:
              schema:
                $ref: '#/components/schemas/Problem'
      deprecated: true
      x-badges:
      - name: DEPRECATED
        position: after
        color: '#f10000'
components:
  schemas:
    KeySet:
      required:
      - id
      - publicKey
      - type
      type: object
      properties:
        id:
          type: string
          description: Key identifier. Maps to the keyId value in the signature header of the push request.
          example: '0'
        type:
          type: string
          description: Key encryption type.
          example: RSA
          enum:
          - RSA
        publicKey:
          type: string
          description: The Base64 encoded public key to use when verifying the signature.
          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==
    Problem:
      required:
      - detail
      - status
      - title
      - type
      - violations
      type: object
      properties:
        type:
          type: string
          description: 'Type URI for this problem. Fixed value: https://api.bol.com/problems.'
          format: uri
          example: https://api.bol.com/problems
        title:
          type: string
          description: Title describing the nature of the problem.
          example: Error validating request. Consult the bol.com API documentation for more information.
        status:
          type: integer
          description: HTTP status returned from the endpoint causing the problem.
          format: int32
        detail:
          type: string
          description: Detailed error message describing in additional detail what caused the service to return this problem.
          example: Bad request
        host:
          type:
          - string
          - 'null'
          description: Host identifier describing the server instance that reported the problem.
          example: Instance-001
        instance:
          type:
          - string
          - 'null'
          description: Full URI path of the resource that reported the problem.
          format: uri
          example: https://api.bol.com//retailer/resource
        violations:
          type: array
          items:
            $ref: '#/components/schemas/Violation'
      description: Describes a problem that occurred interacting with the API.
    SubscriptionResponse:
      required:
      - id
      - resources
      - subscriptionType
      - url
      type: object
      properties:
        id:
          type: string
          description: The unique identifier assigned to each event notification subscription. This ID is used for tracking and managing each subscription.
          example: '1234'
        resources:
          type: array
          items:
            type: string
            description: Array of event types for which the subscription is set. Note that some event types are only available for certain subscription types.
            example: '[''PROCESS_STATUS'']'
            enum:
            - TEST
            - PROCESS_STATUS
            - SHIPMENT
            - PRICE_STAR_BOUNDARY
            - COMPETING_OFFER
            - OFFER_FOR_SALE
            - OFFER_NOT_FOR_SALE
            - ORDER
        url:
          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: The type of subscription. It indicates the platform where the events will be subscribed to. Be aware that certain event types are only available for specific types.
          example: WEBHOOK
          enum:
          - WEBHOOK
          - GCP_PUBSUB
          - AWS_SQS
        enabled:
          type:
          - boolean
          - 'null'
          description: Whether the subscription is enabled and will receive notifications or not. Defaults to true.
          example: true
        identity:
          type:
          - string
          - 'null'
          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>
    SubscriptionsResponse:
      required:
      - subscriptions
      type: object
      properties:
        subscriptions:
          type: array
          items:
            $ref: '#/components/schemas/SubscriptionResponse'
    KeySetResponse:
      required:
      - signatureKeys
      type: object
      properties:
        signatureKeys:
          type: array
          items:
            $ref: '#/components/schemas/KeySet'
    ProcessStatus:
      required:
      - createTimestamp
      - description
      - eventType
      - links
      - status
      type: object
      properties:
        processStatusId:
          type:
          - string
          - 'null'
          description: The process status id.
          example: '1234567'
        entityId:
          type:
          - string
          - 'null'
          description: The id of the object being processed. For example, in case of a shipment process id, you will receive the id of the order item being processed.
          example: '987654321'
        eventType:
          type: string
          description: Name of the requested action that is being processed.
          example: CREATE_SHIPMENT
        description:
          type: string
          description: Describes the action that is being processed.
          example: Example process status description for processing 987654321.
        status:
          type: string
          description: Status of the action being processed.
          example: SUCCESS
          enum:
          - PENDING
          - SUCCESS
          - FAILURE
          - TIMEOUT
        errorMessage:
          type:
          - string
          - 'null'
          description: Shows error message if applicable.
          example: Example process status error message.
        createTimestamp:
          type: string
          description: Time of creation of the response.
          format: date-time
          example: '2018-11-14T09:34:41+01:00'
        links:
          type: array
          description: Lists available actions applicable to this endpoint.
          items:
            $ref: '#/components/schemas/Link'
    Violation:
      required:
      - name
      - reason
      type: object
      properties:
        name:
          type: string
          description: Describes the origin of the error, for instance a field or query parameter validation error.
          example: exampleValue
        reason:
          type: string
          description: Detailed description of the validation error that caused the problem.
          example: 'Request contains invalid value(s): ''INVALID'', allowed values: ALLOWED_VALUE1, ALLOWED_VALUE2.'
      description: Describes a violation that occurred interacting with the API.
    SubscriptionRequest:
      required:
      - resources
      - subscriptionType
      - url
      type: object
      properties:
        resources:
          type: array
          description: Array of event types for which the subscription is set. Note that some event types are only available for certain subscription types.
          example: '[''PROCESS_STATUS'']'
          items:
            type: string
            description: Array of event types for which the subscription is set. Note that some event types are only available for certain subscription types.
            example: '[''PROCESS_STATUS'']'
            enum:
            - PROCESS_STATUS
            - SHIPMENT
            - PRICE_STAR_BOUNDARY
            - COMPETING_OFFER
            - OFFER_FOR_SALE
            - OFFER_NOT_FOR_SALE
            - ORDER
        url:
          minLength: 1
          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: The type of subscription. It indicates the platform where the events will be subscribed to. Be aware that certain event types are only available for specific types.
          example: WEBHOOK
          enum:
          - WEBHOOK
          - GCP_PUBSUB
          - AWS_SQS
        enabled:
          type:
          - boolean
          - 'null'
          description: Whether the subscription is enabled and will receive notifications or not. Defaults to true.
          example: true
        identity:
          type:
          - string
          - 'null'
          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>
    Link:
      type: object
      properties:
        href:
          type: string
        hreflang:
          type: string
        title:
          type: string
        type:
          type: string
        deprecation:
          type: string
        profile:
          type: string
        name:
          type: string
        templated:
          type: boolean
  securitySchemes:
    OAuth2:
      type: http
      description: JWT-based access to api.bol.com
      in: header
      scheme: bearer