openapi: 3.0.3
info:
  title: Distributor API
  description: |-
    The Distributor API offers a comprehensive set of endpoints exclusively for WithSecure™ distributors. It enables partners to perform various actions, including:
    1. Fetch Order: This functionality allowed distributors to retrieve reseller orders placed in WithSecure™ Partner Portal.
    2. Order Confirmation: This functionality allowed distributors to confirm reseller orders placed in WithSecure™ Partner Portal.

    To gain access to the Distributor API, kindly reach out to the WithSecure™ Support team or your dedicated WithSecure™ account manager.

    To avoid throttling, it is best to call the API synchronously or sending in batches of small simultaneous requests. We recommend to send at rate of 10 requests per minute with small delay of 20 seconds between batches.
servers:
  - url: 'https://commercial-test.connect.withsecure.com/ws/rest/distributor/v2'
    description: Staging
  - url: 'https://commercial.connect.withsecure.com/ws/rest/distributor/v2'
    description: Production
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
security:
  - basicAuth: []
tags:
  - name: orders
    description: Information on the endpoints for Distributor API.
paths:
  /orders:
    get:
      tags:
        - orders
      summary: Fetch Order
      description: Retrieve reseller order.
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  header:
                    type: object
                    description: Provides basic information of the query.
                    required:
                      - issue_time
                      - distributor_account_id
                    properties:
                      issue_time:
                        type: string
                        format: date-time
                        description: 'Date and time in UTC, for example, "2007-04-05T14:30" (ISO8601).'
                      distributor_account_id:
                        type: string
                        description: Provided by WithSecure™. Distributor party is the partner using Distributor API. This ID identifies the distributor to be invoiced.
                  orders:
                    type: object
                    description: 'Provides basic information of the reseller, licensee and order list under the licensee in WithSecure™ systems.'
                    required:
                      - supplier_order_number
                      - reseller_po_number
                      - reseller_po_datetime
                      - currency_iso_code
                    properties:
                      supplier_order_number:
                        type: string
                        description: 'Unique order number, which can be used to order the product.'
                      reseller_po_number:
                        type: string
                        description: Purchase order number from reseller.
                      reseller_po_datetime:
                        type: string
                        description: 'Date and time in UTC, for example, "2025-07-07T11:52:01" (ISO8601).'
                      currency_iso_code:
                        type: string
                        description: 'Used Quantity of the subscription. For example, number of endpoints has been used the subscription.'
                      reseller_account:
                        type: object
                        description: Provides identification of the reseller in WithSecure™ systems.
                        required:
                          - reseller_account_id
                          - name
                        properties:
                          reseller_account_id:
                            type: string
                            description: This ID identifies the reseller to be invoiced.
                          name:
                            type: string
                            description: Official name of the reseller.
                          contact:
                            type: object
                            description: Contact details of the contracted reseller.
                            required:
                              - name
                              - email
                            properties:
                              name:
                                type: string
                                description: Name of the contracted reseller.
                              email:
                                type: string
                                description: Email of the contracted reseller.
                      licensee_account:
                        type: object
                        description: Provides identification of the licensee in WithSecure™ systems.
                        required:
                          - licensee_account_id
                          - name
                        properties:
                          licensee_account_id:
                            type: string
                            description: This ID identifies the licensee to be invoiced.
                          name:
                            type: string
                            description: Official name of the licensee.
                          contact:
                            type: object
                            description: Contact details of the contracted licensee.
                            required:
                              - name
                              - email
                            properties:
                              name:
                                type: string
                                description: Name of the contracted licensee.
                              email:
                                type: string
                                description: Email of the contracted licensee.
                      order_lines:
                        type: object
                        description: Details of the order item’s product.
                        required:
                          - sku
                          - subscription_key
                          - sales_type
                          - quantity
                          - unit_price
                          - term_length
                        properties:
                          sku:
                            type: string
                            description: Unique code of the order item’s product.
                          subscription_key:
                            type: string
                            description: Unique license key to be used to install the client software.
                          sales_type:
                            type: string
                            description: The category/method by which of the order.
                          quantity:
                            type: integer
                            description: Quantity of the subscription.
                          unit_price:
                            type: integer
                            description: The cost per single unit of order item’s product.
                          term_length:
                            type: integer
                            description: Subscription term used to prorate eligible products by day or month.
                          promotion_code:
                            type: string
                            description: 'Unique code used to receive discounts, special offers, or exclusive benefits when order item’s product.'
                example:
                  header:
                    issue_time: '2025-07-07T11:52:01'
                    distributor_account_id: A-123456
                  orders:
                    - supplier_order_number: F-60EA8C6EE
                      reseller_po_number: Reseller-order-number-123
                      reseller_po_datetime: '2019-10-17T08:42:49.000Z'
                      currency_iso_code: EUR
                      reseller_account:
                        reseller_account_id: 1-2Q97ZV
                        name: Reseller Company Name Ltd
                        contact:
                          name: John Doe
                          email: john@doe.com
                      licensee_account:
                        licensee_account_id: F011ABMQP1
                        name: Example Customer Company Oy
                        contact:
                          name: First Last
                          email: first.last@company.com
                      order_lines:
                        - sku: W00043
                          subscription_key: CD3N-N84N-BM2X-DBU6-QAN7
                          sales_type: New
                          quantity: 17
                          unit_price: 34.15
                          term_length: 12
                          promotion_code: null
                        - sku: W00030
                          subscription_key: CD3N-N84N-BM2X-DBU6-QAN7
                          sales_type: New
                          quantity: 17
                          unit_price: 34.15
                          term_length: 12
                          promotion_code: null
        '400':
          description: Indicates the problem of the request.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    description: Indicates that the request failed.
                    enum:
                      - error
                  header:
                    type: object
                    description: Provides basic information of the query.
                    properties:
                      issue_time:
                        type: string
                        description: 'Date and time in UTC, for example, "2007-04-05T14:30" (ISO8601).'
                      distributor_account_id:
                        type: string
                        description: This ID identifies the distributor to be invoiced.
                    required:
                      - issue_time
                      - distributor_account_id
                  error:
                    type: string
                    description: Type of error.
                    enum:
                      - Order fetch failed
                  error_description:
                    type: string
                    description: Description about possible cause of error.
                required:
                  - status
                  - error
                  - error_description
              examples:
                Order fetch failed:
                  value:
                    status: error
                    header:
                      issue_time: '2019-05-03T11:42:02'
                      distributor_account_id: A-123456
                    error: Order fetch failed
                    error_description: Failed to fetch order
                  description: Order fetch failed due to data error.
        '500':
          description: Indicates the server encountered error.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    description: Indicates that the request failed.
                    enum:
                      - error
                  header:
                    type: object
                    description: Provides basic information of the query.
                    properties:
                      issue_time:
                        type: string
                        description: 'Date and time in UTC, for example, "2007-04-05T14:30" (ISO8601).'
                      distributor_account_id:
                        type: string
                        description: This ID identifies the distributor to be invoiced.
                    required:
                      - issue_time
                      - distributor_account_id
                  error:
                    type: string
                    description: Type of error.
                    enum:
                      - Service temporarily unavailable
                  error_description:
                    type: string
                    description: Description about possible cause of error.
                    enum:
                      - Service temporarily unavailable
                required:
                  - status
                  - error
                  - error_description
              examples:
                Service temporarily unavailable:
                  value:
                    status: error
                    header:
                      issue_time: '2019-05-03T11:42:02'
                      distributor_account_id: A-123456
                    error: Service temporarily unavailable
                    error_description: Service temporarily unavailable
                  description: Service temporarily unavailable. Please try again after a grace period.
  /order_confirmations:
    post:
      tags:
        - orders
      summary: Order Confirmation
      description: Confirm reseller order.
      consumes:
        - application/json
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                header:
                  type: object
                  required:
                    - issue_time
                    - distributor_account_id
                  description: Provides basic information of the query.
                  properties:
                    issue_time:
                      type: string
                      format: date-time
                      description: 'Date and time in UTC, for example, "2007-04-05T14:30" (ISO8601).'
                    distributor_account_id:
                      type: string
                      description: Provided by WithSecure™. Distributor party is the partner using Distributor API. This ID identifies the distributor to be invoiced.
                order_confirmation:
                  type: object
                  description: Defines the details to confirm order.
                  required:
                    - supplier_order_number
                    - distributor_po_number
                    - reseller_account_id
                  properties:
                    supplier_order_number:
                      type: string
                      description: 'Unique order number, which can be used to order the product.'
                    distributor_po_number:
                      type: string
                      description: Purchase order number from distributor.
                    reseller_account_id:
                      type: string
                      description: This ID identifies the reseller to be invoiced.
            examples:
              Confirm an order:
                value:
                  header:
                    issue_time: '2019-05-03T11:42:01'
                    distributor_account_id: A-123456
                  order_confirmation:
                    supplier_order_number: F-60EA8C6EE
                    distributor_po_number: Dist-order-123456
                    reseller_account_id: F011ABMQP1
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  header:
                    type: object
                    description: Provides basic information of the query.
                    required:
                      - issue_time
                      - distributor_account_id
                    properties:
                      issue_time:
                        type: string
                        format: date-time
                        description: 'Date and time in UTC, for example, "2007-04-05T14:30" (ISO8601).'
                      distributor_account_id:
                        type: string
                        description: Provided by WithSecure™. Distributor party is the partner using Distributor API. This ID identifies the distributor to be invoiced.
                  order:
                    type: object
                    description: Details to confirm order.
                    required:
                      - supplier_order_number
                      - status
                    properties:
                      supplier_order_number:
                        type: string
                        description: 'Unique order number, which used to confirm the order.'
                      status:
                        type: string
                        description: Indicates the status of the order confirmation.
                example:
                  header:
                    issue_time: '2025-07-07T11:52:01'
                    distributor_account_id: A-123456
                  order:
                    supplier_order_number: F-60EA8C6EE
                    status: Order Confirmation Received
        '400':
          description: Indicates the problem of the request.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    description: Indicates that the request failed.
                    enum:
                      - error
                  header:
                    type: object
                    description: Provides basic information of the query.
                    properties:
                      issue_time:
                        type: string
                        description: 'Date and time in UTC, for example, "2007-04-05T14:30" (ISO8601).'
                      distributor_account_id:
                        type: string
                        description: This ID identifies the distributor to be invoiced.
                    required:
                      - issue_time
                      - distributor_account_id
                  error:
                    type: string
                    description: Type of error.
                    enum:
                      - Order confirmation failed
                  error_description:
                    type: string
                    description: Description about possible cause of error.
                required:
                  - status
                  - error
                  - error_description
              examples:
                Order confirmation failed:
                  value:
                    status: error
                    header:
                      issue_time: '2019-05-03T11:42:02'
                      distributor_account_id: A-123456
                    error: Order confirmation failed
                    error_description: Failed to confirm order
                  description: Order confirmation failed due to data error.
        '500':
          description: Indicates the server encountered error.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    description: Indicates that the request failed.
                    enum:
                      - error
                  header:
                    type: object
                    description: Provides basic information of the query.
                    properties:
                      issue_time:
                        type: string
                        description: 'Date and time in UTC, for example, "2007-04-05T14:30" (ISO8601).'
                      distributor_account_id:
                        type: string
                        description: This ID identifies the distributor to be invoiced.
                    required:
                      - issue_time
                      - distributor_account_id
                  error:
                    type: string
                    description: Type of error.
                    enum:
                      - Service temporarily unavailable
                  error_description:
                    type: string
                    description: Description about possible cause of error.
                    enum:
                      - Service temporarily unavailable
                required:
                  - status
                  - error
                  - error_description
              examples:
                Service temporarily unavailable:
                  value:
                    status: error
                    header:
                      issue_time: '2019-05-03T11:42:02'
                      distributor_account_id: A-123456
                    error: Service temporarily unavailable
                    error_description: Service temporarily unavailable
                  description: Service temporarily unavailable. Please try again after a grace period.
