openapi: 3.0.3
info:
  title: WithSecure Commercial API
  description: |
    ## Summary

    The WithSecure Commercial API offers a comprehensive set of endpoints exclusively for WithSecure™ partners operating in the **Total Volume** business model.

    It enables partners, distributors, and resellers to perform various actions, including:

    1. Listing existing subscriptions  
    2. Automated provisioning of Total Volume usage or quantity-based subscriptions  
    3. Listing resellers (for distributors)

    ## Total Volume business model

    The WithSecure Commercial API enables our partners to automate commercial transactions using the **WithSecure Total Volume** business model.

    In the Total Volume business model, all subscriptions are:

    - Continuous until terminated  
    - Priced according to the frame agreement between WithSecure and the partner  
    - Invoiced monthly based on active subscriptions during the billing period  

    Total Volume subscriptions have two types:

    1. **Usage-based** — invoicing is based on the number of active assets during the month  
    2. **Quantity-based** — invoicing is based on active order quantities during the month  

    ## How to gain access

    To gain access to the WithSecure Commercial API, please contact the **WithSecure™ Support Team**
    or your **WithSecure™ account manager**.

    ## API best practices

    - To avoid throttling, call the API synchronously or in **small batches** of simultaneous requests.  
      Recommended rate: **10 requests per minute**, with a **20-second delay** between batches.  
    - Avoid calling **Get Subscriptions** in tight or repeated busy loops.

    ## Notes

    - Reseller management is **not available** in the API. Please contact your WithSecure account manager for details.  
    - The Commercial API does **not fully support business models other than Total Volume** at this time.
servers:
  - url: 'https://commercial-test.connect.withsecure.com/ws/rest/provisioning/v2'
    description: Staging
  - url: 'https://commercial.connect.withsecure.com/ws/rest/provisioning/v2'
    description: Production
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
security:
  - basicAuth: []
tags:
  - name: Organizations
    description: Information on the endpoints related to resellers/distrubotors.
  - name: Subscriptions
    description: Information on the endpoints to get information about subscriptions.
  - name: Manage Total Volume subscriptions
    description: Information on the endpoints for managing Total Volume subscriptions.
  - name: Usage
    description: Endpoints that are used to get usage information.
paths:
  /subscriptions:
    post:
      tags:
        - Manage Total Volume subscriptions
      summary: Create new subscription
      description: Provision a new Total Volume subscription for a new or existing licensee. This endpoint may also be used to grant access to an admin user in the Elements Security Center or to change the licensee (company) name. Granting access and changing the name can only be completed as part of a subscription creation request.
      consumes:
        - application/json
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                header:
                  type: object
                  required:
                    - issue_time
                    - document_id
                    - buyer_account_id
                    - contact_data
                  description: Provides basic information of the business parties involved and identifier for the message itself.
                  properties:
                    issue_time:
                      type: string
                      format: date-time
                      description: 'Date and time in UTC, for example, "2007-04-05T14:30" (ISO8601).'
                    document_id:
                      type: string
                      minLength: 3
                      maxLength: 80
                      description: Reference number for the message. Must be unique.
                    buyer_account_id:
                      type: string
                      minLength: 1
                      maxLength: 30
                      description: 'Provided by WithSecure™. Buyer party is the partner using Provisioning API. This ID identifies the partner''s legal company to be invoiced - can be Distributor ID or Direct Reseller ID. For subscriptions made by Distributors for resellers, distributor_contracted_reseller_account_id should be used.'
                    distributor_contracted_reseller_account_id:
                      type: string
                      minLength: 1
                      maxLength: 30
                      description: Provided by WithSecure™ after distributor contracted reseller has been created. This ID identifies the reseller in 2-tier model.
                licensee_party:
                  type: object
                  required:
                    - name
                    - buyer_assigned_account_id
                    - legal_entity
                  description: 'Provides basic information of the licensee, enabling identification of the licensee in WithSecure™ systems and provisioning of additional subscriptions to the same licensee.'
                  properties:
                    buyer_assigned_account_id:
                      type: string
                      minLength: 1
                      maxLength: 30
                      description: 'Partner''s internal reference number for the licensee that identifies the account.  If account with that id exists, subscription will be attached to that account.  Otherwise new account will be created.'
                    name:
                      type: string
                      minLength: 3
                      maxLength: 255
                      description: Official name for the licensee. This is new name for new licensee. New name will be updated in our system If licensee (identified by buyer_assigned_account_id) already exists.
                    legal_entity:
                      type: object
                      required:
                        - postal_address
                      description: 'Provides basic information of the licensee, enabling identification of the licensee in WithSecure™ systems and provisioning of additional subscriptions to the same licensee.'
                      properties:
                        vat:
                          type: string
                          minLength: 1
                          maxLength: 80
                          description: Value added tax identification number of the licensee.
                        postal_address:
                          type: object
                          required:
                            - street_name
                            - city_name
                            - postal_zone
                            - country_code
                          description: 'Licensee address. Street_name, city_name, postal_zone, country_code is required.'
                          properties:
                            street_name:
                              type: string
                              minLength: 3
                              maxLength: 255
                              description: Street and number.
                            city_name:
                              type: string
                              minLength: 3
                              maxLength: 40
                              description: City.
                            postal_zone:
                              type: string
                              minLength: 1
                              maxLength: 40
                              description: ZIP/Postal code.
                            state_code:
                              type: string
                              minLength: 1
                              maxLength: 3
                              description: 'State code, ISO 3166-2 (for example, "CA" for California). This parameter is used only for addresses in the United States. For addresses in other countries, the parameter can be omitted; if provided, it will be ignored.'
                            country_code:
                              type: string
                              minLength: 2
                              maxLength: 2
                              description: 'Country code, ISO 3166-1 alpha-2, for example, "US" for "United States of America".'
                    sep:
                      type: string
                      minLength: 1
                      maxLength: 255
                      description: |
                        Defines under what organization structure new customer account is placed in Elements Security Center. 
                        When using Elements Security Center and Elements API company details are grouped under the defined SEP organization. 
                        If the SEP organization name is not defined, then company will be placed under SOP organization. 
                        If provided SEP does not exist, it will be created automatically together with the creation of the subscription. 
                    contact_data:
                      type: object
                      required:
                        - first_name
                        - last_name
                        - email
                      description: Licensee contact data to which subscription provisioned
                      properties:
                        first_name:
                          type: string
                          minLength: 1
                          maxLength: 80
                          description: Licensee contact person first name.
                        last_name:
                          type: string
                          minLength: 1
                          maxLength: 80
                          description: Licensee contact person last name.
                        email:
                          type: string
                          format: email
                          description: 'Email address of licensee contact person, maximum of 254 chars (local and domain part as in RFC3696).'
                        phone:
                          type: string
                          minLength: 1
                          maxLength: 11
                          description: Phone of the licensee contact person
                subscription:
                  type: object
                  required:
                    - product
                    - quantity
                    - subscription_type
                  description: 'Defines the product variant, quantity and optional expiration date.'
                  properties:
                    product:
                      type: string
                      minLength: 4
                      maxLength: 4
                      enum:
                        - W00163
                        - W00164
                        - W00165
                        - W00166
                        - W00167
                        - W00168
                        - W00169
                        - W00170
                        - W00171
                        - W00172
                        - W00173
                        - W00144
                        - W00145
                        - W00146
                        - W00147
                        - W00151
                        - W00152
                        - W00154
                        - W00155
                      description: |
                        Product to provision:
                          * 'W00163' - WithSecure™ Elements EPP for Computers.
                          * 'W00164' - WithSecure™ Elements EPP for Computers Premium.
                          * 'W00165' - WithSecure™ Elements EPP for Mobiles.
                          * 'W00166' - WithSecure™ Elements EDR and EPP for Computers Premium.
                          * 'W00167' - WithSecure™ Elements EPP for Servers.
                          * 'W00168' - WithSecure™ Elements EPP for Servers Premium.
                          * 'W00169' - WithSecure™ Elements EDR and EPP for Servers Premium.
                          * 'W00170' - WithSecure™ Elements Collaboration Protection.
                          * 'W00171' - WithSecure™ Elements EDR for Computers.
                          * 'W00172' - WithSecure™ Elements EDR for Servers.
                          * 'W00173' - WithSecure™ Elements Vulnerability Management.(EOS 31.12.2025)
                          * 'W00144' - WithSecure™ Elements Identity Security for Entra ID.
                          * 'W00145' - WithSecure™ Elements Exposure Management for Business.
                          * 'W00146' - WithSecure™ Elements Exposure Management Frontline Add-on.
                          * 'W00147' - WithSecure™ Elements Exposure Management for Cloud.
                          * 'W00151' - WithSecure™ Elements MDR for Endpoints.
                          * 'W00152' - WithSecure™ Elements MDR for Identities.
                          * 'W00154' - WithSecure™ Elements Co-Monitoring Service Out of Office.
                          * 'W00155' - WithSecure™ Elements Co-Monitoring Service 24/7.
                    quantity:
                      type: integer
                      minimum: 1
                      description: 'Quantity of the subscription. For example, number of endpoints allowed to use the subscription. For subscriptions with the type "usage" should be set to 1.'
                    subscription_type:
                      type: string
                      description: 'Subscription type for the current provisioning. Available values: “quantity”, “usage”. Should be the same as previous subscriptions for the same end customer.'
                      enum:
                        - quantity
                        - usage
                    start_date:
                      type: date
                      description: 'Date in UTC, for example, "2007-04-05" (ISO8601) to indicate when the subscription starts. Only the current date is allowed. If the value is not included in the request, it is automatically defaulted to the current date.'
                grant_access:
                  type: object
                  required:
                    - email
                  description: Create the admin user with given email address and grant access to the relevant product portals.
                  properties:
                    email:
                      type: string
                      format: email
                      description: 'Email address, maximum of 254 chars (local and domain part as in RFC3696). Identifies the user to whom the access is granted. Access roles, for example, to which product portal(s) access is given, depends on the product type. The format name+organizationreference@example.com is supported.'
            examples:
              Create a new subscription:
                value:
                  header:
                    issue_time: '2025-05-03T11:42:01'
                    document_id: Partner_Reference-123456
                    buyer_account_id: A-123456
                    distributor_contracted_reseller_account_id: A-345676
                  licensee_party:
                    buyer_assigned_account_id: partner-id-1234
                    name: Licensee Company Name Ltd
                    legal_entity:
                      vat: vat1234567
                      postal_address:
                        street_name: '168, Awesome Street'
                        city_name: Awesome City
                        postal_zone: '12345'
                        state_code: AZ
                        country_code: US
                    contact_data:
                      first_name: John
                      last_name: Doe
                      email: test@example.com
                      phone: '3445678993'
                  subscription:
                    product: W00164
                    quantity: 5
                    subscription_type: quantity
                    start_date: '2025-05-03'
              Create a new subscription + Grant an access:
                value:
                  header:
                    issue_time: '2025-05-03T11:42:01'
                    document_id: Partner_Reference-123456
                    buyer_account_id: A-123456
                    distributor_contracted_reseller_account_id: A-345676
                  licensee_party:
                    buyer_assigned_account_id: partner-id-1234
                    name: Licensee Company Name Ltd
                    legal_entity:
                      vat: vat1234567
                      postal_address:
                        street_name: '168, Awesome Street'
                        city_name: Awesome City
                        postal_zone: '12345'
                        state_code: AZ
                        country_code: US
                      contact_data:
                        first_name: John
                        last_name: Doe
                        email: test@example.com
                        phone: '3445678993'
                  subscription:
                    product: W00164
                    quantity: 5
                    subscription_type: quantity
                  grant_access:
                    email: admin@invalid.com
              Create a new subscription under an existing SEP:
                value:
                  header:
                    issue_time: '2025-05-03T11:42:01'
                    document_id: Partner_Reference-123456
                    buyer_account_id: A-123456
                    distributor_contracted_reseller_account_id: A-345676
                  licensee_party:
                    buyer_assigned_account_id: partner-id-1234
                    name: Licensee Company Name Ltd
                    legal_entity:
                      vat: vat1234567
                      postal_address:
                        street_name: '168, Awesome Street'
                        city_name: Awesome City
                        postal_zone: '12345'
                        state_code: AZ
                        country_code: US
                    contact_data:
                      first_name: John
                      last_name: Doe
                      email: test@example.com
                      phone: '3445678993'
                    sep: Service partner A
                  subscription:
                    product: W00164
                    quantity: 1
                    subscription_type: usage
              Create a new subscription under an existing SEP + Grant an access:
                value:
                  header:
                    issue_time: '2025-05-03T11:42:01'
                    document_id: Partner_Reference-123456
                    buyer_account_id: A-123456
                    distributor_contracted_reseller_account_id: A-123456
                  licensee_party:
                    buyer_assigned_account_id: partner-id-1234
                    name: Licensee Company Name Ltd
                    legal_entity:
                      vat: vat1234567
                      postal_address:
                        street_name: '168, Awesome Street'
                        city_name: Awesome City
                        postal_zone: '12345'
                        state_code: AZ
                        country_code: US
                    contact_data:
                      first_name: John
                      last_name: Doe
                      email: test@example.com
                      phone: '3445678993'
                    sep: Service partner A
                  subscription:
                    product: W00164
                    quantity: 5
                    subscription_type: quantity
                  grant_access:
                    email: admin@invalid.com
              Create a new subscription under an existing SEP + Change company name:
                value:
                  header:
                    issue_time: '2025-05-03T11:42:01'
                    document_id: Partner_Reference-123456
                    buyer_account_id: A-123456
                    distributor_contracted_reseller_account_id: A-123456
                  licensee_party:
                    buyer_assigned_account_id: partner-id-1234
                    name: Licensee Company New Name Ltd
                    legal_entity:
                      vat: vat1234567
                      postal_address:
                        street_name: '168, Awesome Street'
                        city_name: Awesome City
                        postal_zone: '12345'
                        state_code: AZ
                        country_code: US
                    contact_data:
                      first_name: John
                      last_name: Doe
                      email: test@example.com
                      phone: '3445678993'
                    sep: Service partner A
                  subscription:
                    product: W00164
                    quantity: 5
                    subscription_type: quantity
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                      - success
                  header:
                    type: object
                    description: Provides basic information of the query.
                    required:
                      - issue_time
                      - document_id
                      - buyer_account_id
                    properties:
                      issue_time:
                        type: string
                        format: date-time
                        description: 'Date and time in UTC, for example, "2007-04-05T14:30" (ISO8601).'
                      document_id:
                        type: string
                        description: Reference number for the message.
                      buyer_account_id:
                        type: string
                        description: Provided by WithSecure™. Buyer party is the partner using Provisioning API. This ID identifies the partner's legal company to be invoiced.
                      distributor_contracted_reseller_account_id:
                        type: string
                        description: Provided by WithSecure™ after distributor contracted reseller has been created. This ID identifies the reseller in 2-tier model.
                  licensee_party:
                    type: object
                    required:
                      - supplier_assigned_account_id
                      - companyUuid
                    description: Provides identification of the licensee in WithSecure™ systems.
                    properties:
                      supplier_assigned_account_id:
                        type: string
                        description: Identification number of the licensee in WithSecure™ systems.
                      companyUuid:
                        type: string
                        description: Unique identifier of the licensee in WithSecure™ systems.
                  subscription:
                    type: object
                    description: Provides the unique license key to be used to install the client software.
                    required:
                      - subscription_key
                    properties:
                      subscription_key:
                        type: string
                        description: Unique license key to be used to install the client software.
                required:
                  - status
                example:
                  status: success
                  header:
                    issue_time: '2025-05-03T11:42:02'
                    document_id: Partner_Reference-123456
                    buyer_account_id: A-123456
                    distributor_contracted_reseller_account_id: A-567867"
                  licensee_party:
                    supplier_assigned_account_id: B-111111
                    companyUuid: 123e4567-e89b-12d3-a456-426614174000
                  subscription:
                    subscription_key: AAAA-BBBB-CCCC-DDDD-EEEE
        '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).'
                      document_id:
                        type: string
                        description: Reference number for the message.
                      buyer_account_id:
                        type: string
                        description: Provided by WithSecure™. Buyer party is the partner using Provisioning API. This ID identifies the partner's legal company to be invoiced.
                      distributor_contracted_reseller_account_id:
                        type: string
                        description: Provided by WithSecure™ after distributor contracted reseller has been created. This ID identifies the reseller in 2-tier model to invoice and provision the subscriptions.
                  error:
                    type: string
                    description: Type of error.
                    enum:
                      - Invalid request
                      - Subscription creation failed
                  error_description:
                    type: string
                    description: Description about possible cause of error.
                required:
                  - status
                  - error
                  - error_description
              examples:
                Invalid request:
                  value:
                    status: error
                    header:
                      issue_time: '2025-05-03T11:42:02'
                      document_id: Partner_Reference-123456
                      buyer_account_id: A-123456
                      distributor_contracted_reseller_account_id: A-567867
                    error: Invalid request
                    error_description: Invalid expiration_date
                  description: 'Typical syntax errors are mandatory field missing, incorrect field content.'
                Subscription creation failed:
                  value:
                    status: error
                    header:
                      issue_time: '2025-05-03T11:42:02'
                      document_id: Partner_Reference-123456
                      buyer_account_id: A-123456
                    error: Subscription creation failed
                    error_description: Failed to create licensee_party
                  description: Subscription creation failed due to data errors. Typical data errors are conflicting licensee_party/name and failed to create licensee_party.
        '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).'
                      document_id:
                        type: string
                        description: Reference number for the message.
                      buyer_account_id:
                        type: string
                        description: Provided by WithSecure™. Buyer party is the partner using Provisioning API. This ID identifies the partner's legal company to be invoiced.
                      distributor_contracted_reseller_account_id:
                        type: string
                        description: Provided by WithSecure™ after distributor contracted reseller has been created. This ID identifies the reseller in 2-tier model to invoice and provision the subscriptions.
                  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: '2025-05-03T11:42:02'
                      document_id: Partner_Reference-123456
                      buyer_account_id: A-123456
                      distributor_contracted_reseller_account_id: A-123456
                    error: Service temporarily unavailable
                    error_description: Service temporarily unavailable
                  description: Service temporarily unavailable. Please try again after a grace period.
  '/subscriptions/{subscription_key}':
    get:
      tags:
        - Subscriptions
      summary: Get subscription by key
      description: Retrieve subscription details of **Total Volume** subscription by using subscription key.
      parameters:
        - name: subscription_key
          in: path
          required: true
          description: Identifies the subscription_key to retrieve the subscription details.
          schema:
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                      - success
                  header:
                    type: object
                    description: Provides basic information of the query.
                    required:
                      - issue_time
                      - buyer_account_id
                    properties:
                      issue_time:
                        type: string
                        format: date-time
                        description: 'Date and time in UTC, for example, "2007-04-05T14:30" (ISO8601).'
                      buyer_account_id:
                        type: string
                        description: Provided by WithSecure™. Buyer party is the partner using Provisioning API. This ID identifies the partner's legal company to be invoiced.
                      distributor_contracted_reseller_account_id:
                        type: string
                        description: Provided by WithSecure™ after distributor contracted reseller has been created. This ID identifies the reseller in 2-tier model.
                  subscription:
                    type: object
                    description: List out the subscription details
                    required:
                      - subscription_key
                      - product
                      - quantity
                      - used_quantity
                    properties:
                      subscription_key:
                        type: string
                        description: Unique license key to be used to install the client software.
                      product:
                        type: string
                        enum:
                          - W00163
                          - W00164
                          - W00165
                          - W00166
                          - W00167
                          - W00168
                          - W00169
                          - W00170
                          - W00171
                          - W00172
                          - W00173
                          - W00144
                          - W00145
                          - W00146
                          - W00147
                          - W00151
                          - W00152
                          - W00154
                          - W00155
                        description: |
                          Product:
                            * 'W00163' - WithSecure™ Elements EPP for Computers.
                            * 'W00164' - WithSecure™ Elements EPP for Computers Premium.
                            * 'W00165' - WithSecure™ Elements EPP for Mobiles.
                            * 'W00166' - WithSecure™ Elements EDR and EPP for Computers Premium.
                            * 'W00167' - WithSecure™ Elements EPP for Servers.
                            * 'W00168' - WithSecure™ Elements EPP for Servers Premium.
                            * 'W00169' - WithSecure™ Elements EDR and EPP for Servers Premium.
                            * 'W00170' - WithSecure™ Elements Collaboration Protection.
                            * 'W00171' - WithSecure™ Elements EDR for Computers.
                            * 'W00172' - WithSecure™ Elements EDR for Servers.
                            * 'W00173' - WithSecure™ Elements Vulnerability Management.(EOS 31.12.2025)
                            * 'W00144' - WithSecure™ Elements Identity Security for Entra ID.
                            * 'W00145' - WithSecure™ Elements Exposure Management for Business.
                            * 'W00146' - WithSecure™ Elements Exposure Management Frontline Add-on.
                            * 'W00147' - WithSecure™ Elements Exposure Management for Cloud.
                            * 'W00151' - WithSecure™ Elements MDR for Endpoints.
                            * 'W00152' - WithSecure™ Elements MDR for Identities.
                            * 'W00154' - WithSecure™ Elements Co-Monitoring Service Out of Office.
                            * 'W00155' - WithSecure™ Elements Co-Monitoring Service 24/7.
                      quantity:
                        type: integer
                        description: 'Quantity of the subscription. For example, number of endpoints allowed to use the subscription.'
                      used_quantity:
                        type: integer
                        description: 'Used Quantity of the subscription. For example, number of endpoints has been used the subscription.'
                      subscription_type:
                        type: string
                        description: 'Subscription type for the current provisioning. Available values - "quantity", "usage".'
                        enum:
                          - usage
                          - quantity
                      expiration_date:
                        type: string
                        format: date
                        description: 'Date in UTC, for example, "2007-04-05" (ISO8601) to indicate when subscription will expire. Optional parameter shown for terminated subscriptions.'
                required:
                  - status
                example:
                  status: success
                  header:
                    issue_time: '2025-05-03T11:42:02'
                    buyer_account_id: A-123456
                    distributor_contracted_reseller_account_id: A-456678
                  subscription:
                    subscription_key: AAAA-BBBB-CCCC-DDDD-EEEE
                    product: W00169
                    quantity: 15
                    used_quantity: 5
                    subscription_type: quantity
        '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).'
                  error:
                    type: string
                    description: Type of error.
                    enum:
                      - Invalid request
                      - Subscription query failed
                  error_description:
                    type: string
                    description: Description about possible cause of error.
                required:
                  - status
                  - error
                  - error_description
              examples:
                Invalid request:
                  value:
                    status: error
                    header:
                      issue_time: '2025-05-03T11:42:02'
                    error: Invalid request
                    error_description: Invalid request
                  description: Incorrect subscription_key.
                Subscription query failed:
                  value:
                    status: error
                    header:
                      issue_time: '2025-05-03T11:42:02'
                    error: Subscription query failed
                    error_description: Subscription not found
                  description: Subscription query failed due to data error.
                Subscription not supported:
                  value:
                    status: error
                    header:
                      issue_time: '2025-05-03T11:42:02'
                    error: Subscription query failed
                    error_description: The specified subscription key is not supported in the Total Volume model
                  description: 'Subscription key specified exist, but not supported in Total Volume model.'
        '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).'
                    required:
                      - issue_time
                  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: '2025-05-03T11:42:02'
                    error: Service temporarily unavailable
                    error_description: Service temporarily unavailable
                  description: Service temporarily unavailable. Please try again after a grace period.
    put:
      tags:
        - Manage Total Volume subscriptions
      summary: Change subscription
      description: Make changes to an existing **Total Volume** subscription. This endpoint may also be used to grant access to an admin user in the Elements Security Center as part of a subscription change request.
      parameters:
        - name: subscription_key
          in: path
          required: true
          description: Identifies the subscription to change. Value needs to be the same as the subscription_key in request.
          schema:
            type: string
      consumes:
        - application/json
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                header:
                  type: object
                  description: Provides basic information of the business parties involved and identifier for the message itself.
                  required:
                    - issue_time
                    - document_id
                    - buyer_account_id
                  properties:
                    issue_time:
                      type: string
                      format: date-time
                      description: 'Date and time in UTC, for example, "2007-04-05T14:30" (ISO8601).'
                    document_id:
                      type: string
                      minLength: 3
                      maxLength: 80
                      description: Reference number for the message. Must be unique.
                    buyer_account_id:
                      type: string
                      minLength: 1
                      maxLength: 30
                      description: Provided by WithSecure™. Buyer party is the partner using Provisioning API. This ID identifies the partner's legal company to be invoiced.
                subscription_key:
                  type: string
                  minLength: 3
                  maxLength: 80
                  description: Identifies the subscription to change.
                modify_subscription:
                  type: object
                  required: null
                  description: 'Defines new quantity, but does not change the product.'
                  properties:
                    quantity:
                      type: integer
                      minimum: 1
                      description: 'Quantity of the subscription. For example, number of endpoints allowed to use the subscription. New quantity must be greater or equal to the actual usage of the subscription. Any additional computers reserving licenses must be deleted in advance by using the WithSecure™ Elements Security Center or Elements API.'
                change_product:
                  type: object
                  required:
                    - product
                  description: Change the product (upgrade).
                  properties:
                    product:
                      type: string
                      minLength: 6
                      maxLength: 6
                      description: |
                        Change the product (upgrade).
                          * W00163 can be changed to W00164, W00166.
                          * W00164 can be changed to W00166.
                          * W00167 can be changed to W00168, W00169.
                          * W00168 can be changed to W00169.
                          * W00171 can be changed to W00166.
                          * W00172 can be changed to W00169.
                grant_access:
                  type: object
                  required:
                    - email
                  description: Create the admin user with given email address and grant access to Elements Security Center. **Please note that revoke access is not supported in the current version of API.**
                  properties:
                    email:
                      type: string
                      format: email
                      description: 'Email address, maximum of 254 chars (local and domain part as in RFC3696). Identifies the user to whom the access is granted. Access roles, for example, to which product portal(s) access is given, depends on the product type. The format name+organizationreference@example.com is supported.'
              required:
                - subscription_key
            examples:
              Modify a subscription:
                value:
                  header:
                    issue_time: '2025-05-03T11:42:01'
                    document_id: Partner_Reference-123456
                    buyer_account_id: A-123456
                  subscription_key: AAAA-BBBB-CCCC-DDDD-EEEE
                  modify_subscription:
                    quantity: 5
              Change a product:
                value:
                  header:
                    issue_time: '2025-05-03T11:42:01'
                    document_id: Partner_Reference-123456
                    buyer_account_id: A-123456
                  subscription_key: AAAA-BBBB-CCCC-DDDD-EEEE
                  change_product:
                    product: W00166
              Grant an access:
                value:
                  header:
                    issue_time: '2025-05-03T11:42:01'
                    document_id: Partner_Reference-123456
                    buyer_account_id: A-123456
                  subscription_key: AAAA-BBBB-CCCC-DDDD-EEEE
                  grant_access:
                    email: admin@invalid.com
              Modify a subscription + Grant an access:
                value:
                  header:
                    issue_time: '2025-05-03T11:42:01'
                    document_id: Partner_Reference-123456
                    buyer_account_id: A-123456
                  subscription_key: AAAA-BBBB-CCCC-DDDD-EEEE
                  modify_subscription:
                    quantity: 5
                  grant_access:
                    email: admin@invalid.com
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                      - success
                  header:
                    type: object
                    description: Provides basic information of the query.
                    required:
                      - issue_time
                      - document_id
                      - buyer_account_id
                    properties:
                      issue_time:
                        type: string
                        format: date-time
                        description: 'Date and time in UTC, for example, "2007-04-05T14:30" (ISO8601).'
                      document_id:
                        type: string
                        description: Reference number for the message.
                      buyer_account_id:
                        type: string
                        description: Provided by WithSecure™. Buyer party is the partner using Commercial API. This ID identifies the partner's legal company to be invoiced.
                  licensee_party:
                    type: object
                    description: Provides identification of the licensee in WithSecure™ systems.
                    required:
                      - supplier_assigned_account_id
                    properties:
                      supplier_assigned_account_id:
                        type: string
                        description: Identification number of the licensee in WithSecure™ systems.
                  subscription:
                    type: object
                    description: Provides the unique license key to be used to install the client software.
                    required:
                      - subscription_key
                    properties:
                      subscription_key:
                        type: string
                        description: Unique license key to be used to install the client software.
                required:
                  - status
                example:
                  status: success
                  header:
                    issue_time: '2025-05-03T11:42:02'
                    document_id: Partner_Reference-123456
                    buyer_account_id: A-123456
                  licensee_party:
                    supplier_assigned_account_id: B-111111
                  subscription:
                    subscription_key: AAAA-BBBB-CCCC-DDDD-EEEE
        '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).'
                      document_id:
                        type: string
                        description: Reference number for the message.
                      buyer_account_id:
                        type: string
                        description: Provided by WithSecure™. Buyer party is the partner using Provisioning API. This ID identifies the partner's legal company to be invoiced.
                  error:
                    type: string
                    description: Type of error.
                    enum:
                      - Invalid request
                      - Subscription modification failed
                  error_description:
                    type: string
                    description: Description about possible cause of error.
                required:
                  - status
                  - error
                  - error_description
              examples:
                Invalid request:
                  value:
                    status: error
                    header:
                      issue_time: '2025-05-03T11:42:02'
                      document_id: Partner_Reference-123456
                      buyer_account_id: A-123456
                    error: Invalid request
                    error_description: Invalid subscription_key
                  description: 'Typical syntax errors are mandatory field missing, incorrect field content.'
                Subscription modification failed:
                  value:
                    status: error
                    header:
                      issue_time: '2025-05-03T11:42:02'
                      document_id: Partner_Reference-123456
                      buyer_account_id: A-123456
                    error: Subscription modification failed
                    error_description: Failed to update quantity
                  description: Subscription modification 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).'
                      document_id:
                        type: string
                        description: Reference number for the message.
                      buyer_account_id:
                        type: string
                        description: Provided by WithSecure™. Buyer party is the partner using Provisioning API. This ID identifies the partner's legal company to be invoiced.
                  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: '2025-05-03T11:42:02'
                      document_id: Partner_Reference-123456
                      buyer_account_id: A-123456
                    error: Service temporarily unavailable
                    error_description: Service temporarily unavailable
                  description: Service temporarily unavailable. Please try again after a grace period.
  '/subscriptions?buyer_assigned_account_id={buyer_assigned_account_id}&include_expired={include_expired}':
    get:
      tags:
        - Subscriptions
      summary: Get subscriptions by buyer assigned account Id
      description: |
        Used by **Resellers** to retrieve subscriptions details under a licensee by using partner's buyer assigned account Id for the licensee.  
        If specified licensee has Evergreen Deal Based subscriptions, they will be returned in the response together as Total Volume subscriptions.  

        **Limitations:**

        - In the current version of the API, there is a limitation to split Total Volume quantity subscriptions and Deal Based Evergreen.  
        - Total Volume subscriptions and Deal Based Evergreen subscriptions should not be mixed under a single reseller.
      parameters:
        - name: buyer_assigned_account_id
          in: query
          required: true
          description: Partner's internal buyer assigned account Id for the licensee.
          schema:
            type: string
        - name: include_expired
          in: query
          required: false
          description: To include the expired subscription. Can be true/false. Default value true.
          schema:
            type: boolean
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                      - success
                  header:
                    type: object
                    description: Provides basic information of the query.
                    required:
                      - issue_time
                      - buyer_account_id
                    properties:
                      issue_time:
                        type: string
                        format: date-time
                        description: 'Date and time in UTC, for example, "2007-04-05T14:30" (ISO8601).'
                      buyer_account_id:
                        type: string
                        description: Provided by WithSecure™. Buyer party is the partner using Provisioning API. This ID identifies the partner's legal company to be invoiced.
                      distributor_contracted_reseller_account_id:
                        type: string
                        description: Provided by WithSecure™ after distributor contracted reseller has been created. This ID identifies the reseller in 2-tier model.
                  licensees:
                    type: object
                    description: Provides basic information of the licensee and subscription list under the licensee in WithSecure™ systems.
                    properties:
                      licensee_party:
                        type: object
                        description: Provides basic information of the licensee in WithSecure™ systems.
                        required:
                          - supplier_assigned_account_id
                          - buyer_assigned_account_id
                          - name
                        properties:
                          supplier_assigned_account_id:
                            type: string
                            description: Identification number of the licensee in WithSecure™ systems.
                          buyer_assigned_account_id:
                            type: string
                            description: Partner's internal reference number for the licensee.
                          name:
                            type: string
                            description: Name of the licensee.
                          sep:
                            type: string
                            description: Organization hierarchy where customer account is placed in Elements Security Center.
                      subscription:
                        type: object
                        description: List out the subscription details
                        required:
                          - subscription_key
                          - product
                          - quantity
                          - used_quantity
                        properties:
                          subscription_key:
                            type: string
                            description: Unique license key to be used to install the client software.
                          product:
                            type: string
                            enum:
                              - W00163
                              - W00164
                              - W00165
                              - W00166
                              - W00167
                              - W00168
                              - W00169
                              - W00170
                              - W00171
                              - W00172
                              - W00173
                              - W00144
                              - W00145
                              - W00146
                              - W00147
                              - W00151
                              - W00152
                              - W00154
                              - W00155
                            description: |
                              Product:
                                * 'W00163' - WithSecure™ Elements EPP for Computers.
                                * 'W00164' - WithSecure™ Elements EPP for Computers Premium.
                                * 'W00165' - WithSecure™ Elements EPP for Mobiles.
                                * 'W00166' - WithSecure™ Elements EDR and EPP for Computers Premium.
                                * 'W00167' - WithSecure™ Elements EPP for Servers.
                                * 'W00168' - WithSecure™ Elements EPP for Servers Premium.
                                * 'W00169' - WithSecure™ Elements EDR and EPP for Servers Premium.
                                * 'W00170' - WithSecure™ Elements Collaboration Protection.
                                * 'W00171' - WithSecure™ Elements EDR for Computers.
                                * 'W00172' - WithSecure™ Elements EDR for Servers.
                                * 'W00173' - WithSecure™ Elements Vulnerability Management.(EOS 31.12.2025)
                                * 'W00144' - WithSecure™ Elements Identity Security for Entra ID.
                                * 'W00145' - WithSecure™ Elements Exposure Management for Business.
                                * 'W00146' - WithSecure™ Elements Exposure Management Frontline Add-on.
                                * 'W00147' - WithSecure™ Elements Exposure Management for Cloud.
                                * 'W00151' - WithSecure™ Elements MDR for Endpoints.
                                * 'W00152' - WithSecure™ Elements MDR for Identities.
                                * 'W00154' - WithSecure™ Elements Co-Monitoring Service Out of Office.
                                * 'W00155' - WithSecure™ Elements Co-Monitoring Service 24/7.
                          quantity:
                            type: integer
                            description: 'Quantity of the subscription. For example, number of endpoints allowed to use the subscription.'
                          used_quantity:
                            type: integer
                            description: 'Used Quantity of the subscription. For example, number of endpoints has been used the subscription.'
                          subscription_type:
                            type: string
                            description: 'Subscription type for the current provisioning. Available values - "quantity", "usage".'
                            enum:
                              - usage
                              - quantity
                          expiration_date:
                            type: string
                            format: date
                            description: 'Date in UTC, for example, "2007-04-05" (ISO8601) to indicate when subscription will expire. Optional parameter avaiable for terminated subscriptions.'
                required:
                  - status
                example:
                  status: success
                  header:
                    issue_time: '2020-11-17T16:41:33.000Z'
                    buyer_account_id: F001150674
                    distributor_contracted_reseller_account_id: F001150334
                  licensees:
                    - licensee_party:
                        supplier_assigned_account_id: 1234CDEFG
                        buyer_assigned_account_id: Your-customer-id-1
                        name: Licensee Company Name Ltd
                        sep: Service partner A
                      subscriptions:
                        - subscription_key: AAAA-BBBB-CCCC-DDDD-EEEE
                          product: W00163
                          quantity: 15
                          used_quantity: 10
                          expiration_date: '2021-09-01'
                        - subscription_key: AAAA-BBBB-CCCC-DDDD-FFFF
                          product: W00164
                          quantity: 5
                          used_quantity: 2
        '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).'
                  error:
                    type: string
                    description: Type of error.
                    enum:
                      - Invalid request
                      - Subscription query failed
                  error_description:
                    type: string
                    description: Description about possible cause of error.
                required:
                  - status
                  - error
                  - error_description
              examples:
                Invalid request:
                  value:
                    status: error
                    error: Invalid request
                    error_description: Invalid request
                  description: Incorrect query param given.
                Subscription query failed:
                  value:
                    status: error
                    header:
                      issue_time: '2025-05-03T11:42:02'
                    error: Subscription query failed
                    error_description: Subscription not found
                  description: Subscription query 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).'
                    required:
                      - issue_time
                  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: '2025-05-03T11:42:02'
                    error: Service temporarily unavailable
                    error_description: Service temporarily unavailable
                  description: Service temporarily unavailable. Please try again after a grace period.
  '/subscriptions?reseller_account_id={reseller_account_id}&include_expired={include_expired}&anchor={anchor}':
    get:
      tags:
        - Subscriptions
      summary: Get subscriptions by reseller account id
      description: |
        Retrieve subscription details under a reseller with a **Total Volume agreement** by using the reseller's unique identifier provided by WithSecure.

        This endpoint can be used by **Direct Resellers** and **Distributors**, but information is returned only for a **single reseller per request**.

        If the specified reseller has **Evergreen Deal-Based subscriptions**, they will be included in the response together with Total Volume subscriptions.

        To retrieve the list of **Contracted Resellers** under a Distributor with a Total Volume agreement, Distributors can use the **Get Total Volume Resellers** endpoint.

        **Limitations:**  

        - In the current version of the API, it is not possible to split Total Volume quantity subscriptions and Deal-Based Evergreen subscriptions.
        - Total Volume subscriptions and Deal-Based Evergreen subscriptions should **not** be mixed under a single reseller.
      parameters:
        - name: reseller_account_id
          in: query
          required: true
          description: Unique identifier of the Distributor Contracted Reseller in 2-tier model or Direct Reseller in WithSecure™ systems.
          schema:
            type: string
        - name: include_expired
          in: query
          required: false
          description: To include the expired subscription. Can be true/false. Default value true.
          schema:
            type: boolean
        - name: anchor
          in: query
          required: false
          description: 'Anchor pointing to the page that should be retrieved. If not specified, will return the first page.'
          schema:
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                      - success
                  header:
                    type: object
                    description: Provides basic information of the query.
                    required:
                      - issue_time
                      - buyer_account_id
                    properties:
                      issue_time:
                        type: string
                        format: date-time
                        description: 'Date and time in UTC, for example, "2007-04-05T14:30" (ISO8601).'
                      buyer_account_id:
                        type: string
                        description: Provided by WithSecure™. Buyer party is the partner using Provisioning API. This ID identifies the partner's legal company to be invoiced.
                      distributor_contracted_reseller_account_id:
                        type: string
                        description: Provided by WithSecure™ after distributor contracted reseller has been created. This ID identifies the reseller in 2-tier model.
                  licensees:
                    type: object
                    description: Provides basic information of the licensee and subscription list under the licensee in WithSecure™ systems.
                    properties:
                      licensee_party:
                        type: object
                        description: Provides basic information of the licensee in WithSecure™ systems.
                        required:
                          - supplier_assigned_account_id
                          - buyer_assigned_account_id
                          - name
                        properties:
                          supplier_assigned_account_id:
                            type: string
                            description: Identification number of the licensee in WithSecure™ systems.
                          buyer_assigned_account_id:
                            type: string
                            description: Partner's internal reference number for the licensee.
                          name:
                            type: string
                            description: Name of the licensee.
                          sep:
                            type: string
                            description: Organization hierarchy where customer account is placed in Elements Security Center.
                      subscription:
                        type: array
                        description: List out the subscription details
                        required:
                          - subscription_key
                          - product
                          - quantity
                          - used_quantity
                        properties:
                          subscription_key:
                            type: string
                            description: Unique license key to be used to install the client software.
                          product:
                            type: string
                            enum:
                              - W00163
                              - W00164
                              - W00165
                              - W00166
                              - W00167
                              - W00168
                              - W00169
                              - W00170
                              - W00171
                              - W00172
                              - W00173
                              - W00144
                              - W00145
                              - W00146
                              - W00147
                              - W00151
                              - W00152
                              - W00154
                              - W00155
                            description: |
                              Product:
                                * 'W00163' - WithSecure™ Elements EPP for Computers.
                                * 'W00164' - WithSecure™ Elements EPP for Computers Premium.
                                * 'W00165' - WithSecure™ Elements EPP for Mobiles.
                                * 'W00166' - WithSecure™ Elements EDR and EPP for Computers Premium.
                                * 'W00167' - WithSecure™ Elements EPP for Servers.
                                * 'W00168' - WithSecure™ Elements EPP for Servers Premium.
                                * 'W00169' - WithSecure™ Elements EDR and EPP for Servers Premium.
                                * 'W00170' - WithSecure™ Elements Collaboration Protection.
                                * 'W00171' - WithSecure™ Elements EDR for Computers.
                                * 'W00172' - WithSecure™ Elements EDR for Servers.
                                * 'W00173' - WithSecure™ Elements Vulnerability Management.(EOS 31.12.2025)
                                * 'W00144' - WithSecure™ Elements Identity Security for Entra ID.
                                * 'W00145' - WithSecure™ Elements Exposure Management for Business.
                                * 'W00146' - WithSecure™ Elements Exposure Management Frontline Add-on.
                                * 'W00147' - WithSecure™ Elements Exposure Management for Cloud.
                                * 'W00151' - WithSecure™ Elements MDR for Endpoints.
                                * 'W00152' - WithSecure™ Elements MDR for Identities.
                                * 'W00154' - WithSecure™ Elements Co-Monitoring Service Out of Office.
                                * 'W00155' - WithSecure™ Elements Co-Monitoring Service 24/7.
                          quantity:
                            type: integer
                            description: 'Quantity of the subscription. For example, number of endpoints allowed to use the subscription.'
                          used_quantity:
                            type: integer
                            description: 'Used Quantity of the subscription. For example, number of endpoints has been used the subscription.'
                          subscription_type:
                            type: string
                            description: 'Subscription type for the current provisioning. Available values - "quantity", "usage".'
                            enum:
                              - usage
                              - quantity
                          expiration_date:
                            type: string
                            format: date
                            description: 'Date in UTC, for example, "2007-04-05" (ISO8601) to indicate when subscription will expire. Information available for terminated subscriptions.'
                  paging:
                    type: object
                    description: Provides the paging info
                    properties:
                      next_anchor:
                        type: string
                        description: 'Anchor pointing to the page that should be retrieved. If not specified, will return the first page.'
                        required:
                          - next_anchor
                required:
                  - status
                example:
                  status: success
                  header:
                    issue_time: '2020-11-17T16:41:33.000Z'
                    buyer_account_id: F001150674
                  licensees:
                    - licensee_party:
                        supplier_assigned_account_id: 1234CDEFG
                        buyer_assigned_account_id: Your-customer-id-1
                        name: Licensee Company A Ltd
                      subscriptions:
                        - subscription_key: AAAA-BBBB-CCCC-DDDD-EEEE
                          product: W00163
                          quantity: 15
                          used_quantity: 10
                          expiration_date: '2021-09-01'
                    - licensee_party:
                        supplier_assigned_account_id: 2345CDEFG
                        buyer_assigned_account_id: Your-customer-id-2
                        name: Licensee Company B Ltd
                        sep: Service partner B
                      subscriptions:
                        - subscription_key: AAAA-BBBB-CCCC-DDDD-FFFF
                          product: W00164
                          quantity: 5
                          used_quantity: 2
                  paging:
                    next_anchor: ZXlKa2IyMWhhVzVmYTJWNUlqb2dJbU52YlM1bWMyVmpkwbgda7TG1OdmNuQnZjbUYwWlhOMWFYUmxMbk4xWW5OamNtbHdkR2x2Ym5NNk1EYzBPR1pqTWpRdE1qZzRZeTAwTjJGa0xXSmpaak10T1RZNE9HVTVZalF5TkRSaElpd2dJbkZwTjE5emF5STZJQ0oyWVd4cFpEc3lNREl5TFRBeExURXhWREl6T2pVNU9qVTVXaUlzSUNKeGFUZGZjR3NpT2lBaWNXazNPMk52YlM1bWMyVmpkWEpsTG1OdmNuQnZjbUYwWlhOMWFYUmxMbk4xWW5OamNtbHdkR2x2Ym5NN05qbG1Zall3TnpJdE1qRmtPQzAwT1RBd0xUazNOekl0TldKaE1tRmhNelk0WlRCaEluMD07MA==1w=0o3YnV5ZXJfYWNasgd6dkdF9pZD1GRjAwMDYwODcxOSZpbmNsdWRlX2V4cGlyZWQ9dHJ1ZQ==
        '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).'
                  error:
                    type: string
                    description: Type of error.
                    enum:
                      - Invalid request
                      - Subscription query failed
                  error_description:
                    type: string
                    description: Description about possible cause of error.
                required:
                  - status
                  - error
                  - error_description
              examples:
                Invalid request:
                  value:
                    status: error
                    error: Invalid request
                    error_description: Invalid request
                  description: Incorrect query param given.
                Subscription query failed:
                  value:
                    status: error
                    header:
                      issue_time: '2025-05-03T11:42:02'
                    error: Subscription query failed
                    error_description: Subscription not found
                  description: Subscription query 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).'
                    required:
                      - issue_time
                  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: '2025-05-03T11:42:02'
                    error: Service temporarily unavailable
                    error_description: Service temporarily unavailable
                  description: Service temporarily unavailable. Please try again after a grace period.
  '/subscriptions/{subscription_key}?expiration_date={expiration_date}':
    delete:
      tags:
        - Manage Total Volume subscriptions
      summary: Terminate subscription
      description: Terminate **Total Volume** subscription of licensee by using subscription key
      parameters:
        - name: subscription_key
          in: path
          required: true
          description: Identifies the subscription to terminate.
          schema:
            type: string
        - name: expiration_date
          in: query
          required: true
          description: 'Date in UTC, for example, "2007-04-05" (ISO8601). Expiration date value should be current date or a future date, but not greater that 31 day from current date.'
          schema:
            type: date
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                      - success
                required:
                  - status
                example:
                  status: success
        '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
                  error:
                    type: string
                    description: Type of error.
                    enum:
                      - Invalid request
                      - Subscription terminate failed
                  error_description:
                    type: string
                    description: Description about possible cause of error.
                required:
                  - status
                  - error
                  - error_description
              examples:
                Invalid request:
                  value:
                    status: error
                    error: Invalid request
                    error_description: Invalid request
                  description: 'Typical syntax errors are missing mandatory url parameters, incorrect url parameters content.'
                Subscription terminate failed:
                  value:
                    status: error
                    error: Subscription terminate failed
                    error_description: Failed to terminate subscription
                  description: Terminate subscription failed due to data errors. Typical data errors are subscription key not exist and failed to terminate subscription.
        '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
                  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
                    error: Service temporarily unavailable
                    error_description: Service temporarily unavailable
                  description: Service temporarily unavailable. Please try again after a grace period.
  '/usages/{buyer_account_id}/{year}/{month}?distributor_contracted_reseller_id={distributor_contracted_reseller_id}':
    get:
      tags:
        - Usage
      summary: Get Usage
      description: |
        Used by **Distributors** and **Direct Resellers** to get the full usage report of all licensees returned for the given month.   
        API provide functionality to fetch aggregated **Total Volume** subscription usage information for billing purposes through API.  
        Allow Distributors to filter response based on Contracted Reseller Id provided in the request.  
        Returns only usage related to usage based subscriptions, does not return information about quantity based subscriptions.
      parameters:
        - name: buyer_account_id
          in: path
          required: true
          description: Unique identifier of the partners in WithSecure™ systems.
          schema:
            type: string
        - name: month
          in: path
          required: true
          description: 'Two characters to indicate month of requested period. For one character, 0 should be added in the start. Example:06.'
          schema:
            type: string
        - name: year
          in: path
          required: true
          description: 'Four characters to indicate requested year of requested poeriod. Example:2025.'
          schema:
            type: string
        - name: distributor_contracted_reseller_id
          in: query
          required: false
          description: 'Provided by WithSecure™ after distributor contracted reseller has been created. This ID identifies the reseller in 2-tier model. If provided, only subscriptions of specific contracted reseller will be returned.'
          schema:
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                      - success
                  header:
                    type: object
                    description: Provides basic information of the usage query.
                    required:
                      - issue_time
                      - buyer_account_id
                      - year
                      - month
                    properties:
                      issue_time:
                        type: string
                        format: date-time
                        description: 'Date and time in UTC, for example, "2007-04-05T14:30" (ISO8601). Timestamp for the message.'
                      buyer_account_id:
                        type: string
                        description: Provided by WithSecure™. Buyer party is the partner using Usage API. This ID identifies the partner's legal company to be invoiced.
                      year:
                        type: integer
                        description: Year of the requested usage report.
                      month:
                        type: integer
                        description: Month of the requested usage report.
                  usage:
                    type: array
                    description: List of usage records for licensees.
                    items:
                      type: object
                      required:
                        - supplier_assigned_account_id
                        - buyer_assigned_account_id
                        - licensee_party_name
                        - licensee_party_vat
                        - features
                      properties:
                        supplier_assigned_account_id:
                          type: string
                          description: WithSecure™ internal reference number for the licensee. Unique for each licensee.
                        buyer_assigned_account_id:
                          type: string
                          description: Partner’s internal reference number for the licensee (end customer). Must be unique.
                        licensee_party_name:
                          type: string
                          description: Name of the licensee (end customer).
                        licensee_party_legal_identifier:
                          type: string
                          description: VAT identifier of the licensee.
                        distributor_contracted_reseller_account_id:
                          type: string
                          description: Provided by WithSecure™ after a distributor-contracted reseller has been created.
                        distributor_contracted_reseller_partner_class:
                          type: string
                          description: 'Classification of the reseller (e.g., Registered).'
                        subscriptions:
                          type: array
                          description: List of product or feature usages for the month.
                          items:
                            type: object
                            required:
                              - quantity
                              - product_name
                            properties:
                              quantity:
                                type: integer
                                description: 'Quantity of the product usage during the given month, e.g., number of active devices.'
                              product_code:
                                type: string
                                description: Identifier of the product (if applicable).
                              feature_code:
                                type: string
                                description: Identifier of the feature (if applicable).
                              product_name:
                                type: string
                                description: Descriptive name of the product or feature.
                required:
                  - status
                  - header
                  - usage
                example:
                  status: success
                  header:
                    issue_time: '2020-06-01T11:42:02'
                    buyer_account_id: A123456
                    year: '2025'
                    month: '05'
                  usage:
                    - supplier_assigned_account_id: 1234CDEFG
                      buyer_assigned_account_id: Your-customer-id-1
                      licensee_party_name: End Customer A
                      licensee_party_legal_identifier: FI001010101
                      distributor_contracted_reseller_account_id: FF12345678
                      distributor_contracted_reseller_partner_class: Registered
                      subscriptions:
                        - quantity: 10
                          product_code: W00163
                          product_name: WithSecure™ Elements EPP for Computers
                        - quantity: 41
                          product_code: W00164
                          product_name: WithSecure™ Elements EPP for Computers Premium
                        - quantity: 21
                          feature_code: W00144
                          product_name: WithSecure™ Elements Identity Security for Entra ID
                        - quantity: 15
                          feature_code: W00145
                          product_name: WithSecure™ Elements Exposure Management for Business
                        - quantity: 30
                          feature_code: W00151
                          product_name: WithSecure™ Elements MDR for Endpoints
        '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).'
                  error:
                    type: string
                    description: Type of error.
                    enum:
                      - Invalid request
                  error_description:
                    type: string
                    description: Description about possible cause of error.
                required:
                  - status
                  - error
                  - error_description
              examples:
                Invalid request:
                  value:
                    status: error
                    error: Invalid request
                    header:
                      issue_time: '2025-05-03T11:42:02'
                  description: Incorrect query param given.
                Usage query failed:
                  value:
                    status: error
                    header:
                      issue_time: '2025-05-03T11:42:02'
                    error: Usage query failed
                    error_description: Usages not found
                  description: Usages query failed due to data error.
        '500':
          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).'
                  error:
                    type: string
                    description: Type of error.
                    enum:
                      - Invalid request
                  error_description:
                    type: string
                    description: Description about possible cause of error.
                required:
                  - status
                  - error
                  - error_description
              examples:
                Internal Server Erro:
                  value:
                    status: error
                    error: Service temporarily unavailable
                    error_description: Service temporarily unavailable
                    header:
                      issue_time: '2025-05-03T11:42:02'
                  description: Incorrect query param given.
  /resellers:
    get:
      tags:
        - Organizations
      summary: Get Total Volume Resellers
      description: |
        Used by **Distributors** to get list of **Distributor Contracted Resellers** with **Total Volume Frame Agreement** under specific Distributor.  
        Request doesn't require any parameters and use Buyer Account Id of the Distributor based on buyer_account_id received after authorization. 
        Response contains only resellers that have Total Volume Frame Agreement under that distributor.  
        **Deal Based resellers are not presented** in the response.
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                      - success
                  header:
                    type: object
                    description: Provides basic information of the query.
                    required:
                      - issue_time
                      - buyer_account_id
                    properties:
                      issue_time:
                        type: string
                        format: date-time
                        description: 'Date and time in UTC, for example, "2025-04-05T14:30" (ISO8601).'
                      buyer_account_id:
                        type: string
                        description: Provided by WithSecure™. Buyer party is the partner using Commercial API. This ID identifies the partner's legal company to be invoiced.
                  contracted_resellers:
                    type: array
                    description: List of contracted resellers under specified distributor with Total Volume Frame Agreement.
                    items:
                      type: object
                      required:
                        - reseller_name
                        - reseller_account_id
                      properties:
                        reseller_name:
                          type: string
                          description: Name of the distributor contracted reseller.
                          minLength: 3
                          maxLength: 255
                        reseller_account_id:
                          type: string
                          description: Provided by WithSecure™ after distributor contracted reseller has been created. This ID identifies the reseller in 2-tier model.
                          minLength: 1
                          maxLength: 30
                required:
                  - status
                  - header
                  - contracted_resellers
                example:
                  status: success
                  header:
                    issue_time: '2020-06-01T11:42:02'
                    buyer_account_id: A123456
                  contracted_resellers:
                    - reseller_name: Reseller Company A
                      reseller_account_id: FF34455
                    - reseller_name: Reseller Company B
                      reseller_account_id: FF9999
        '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).'
                      buyer_account_id:
                        type: string
                        description: Provided by WithSecure™. Buyer party is the partner using Commercial API. This ID identifies the partner's legal company to be invoiced.
                  error:
                    type: string
                    description: Type of error.
                    enum:
                      - Invalid request
                  error_description:
                    type: string
                    description: Description about possible cause of error.
                required:
                  - status
                  - error
                  - error_description
              examples:
                Invalid request:
                  value:
                    status: error
                    header:
                      issue_time: '2025-05-03T11:42:02'
                      buyer_account_id: A-123456
                    error: Invalid request
                    error_description: Invalid request
                  description: Invalid request.
                Resellers query failed:
                  value:
                    status: error
                    header:
                      issue_time: '2025-05-03T11:42:02'
                      buyer_account_id: A-123456
                    error: No Contracted Resellers
                    error_description: There are no Total Volume Contracted Resellers under the current buyer account.
                  description: Reseller query failed due to a data error.
        '500':
          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).'
                      buyer_account_id:
                        type: string
                        description: Provided by WithSecure™. Buyer party is the partner using Commercial API. This ID identifies the partner's legal company to be invoiced.
                  error:
                    type: string
                    description: Type of error.
                    enum:
                      - Invalid request
                  error_description:
                    type: string
                    description: Description about possible cause of error.
                required:
                  - status
                  - error
                  - error_description
              examples:
                Internal Server Error:
                  value:
                    status: error
                    header:
                      issue_time: '2025-05-03T11:42:02'
                      buyer_account_id: A-123456
                    error: Service temporarily unavailable
                    error_description: Service temporarily unavailable
                  description: Service temporarily unavailable. Retry after 1 minute.
