Genesys Billing API

swagger: '2.0'
info:
  description: With the PureCloud Platform API, you can control all aspects of your PureCloud environment. With the APIs you can access the system configuration, manage conversations and more.
  version: v2
  title: PureCloud Platform Agent Assistants Billing API
  termsOfService: https://help.genesys.cloud/articles/terms-and-conditions/
  contact:
    name: PureCloud Developer Evangelists
    url: https://developer.genesys.cloud/
    email: DeveloperEvangelists@genesys.com
  license:
    name: UNLICENSED
    url: https://help.genesys.cloud/articles/terms-and-conditions/
host: api.mypurecloud.com
schemes:
- https
consumes:
- application/json
produces:
- application/json
tags:
- name: Billing
  description: ''
  externalDocs:
    description: billing Documentation
    url: https://developer.genesys.cloud/billing/
paths:
  /api/v2/billing/reports/billableusage:
    get:
      tags:
      - Billing
      summary: Get a report of the billable license usages
      description: Report is of the billable usages (e.g. licenses and devices utilized) for a given period. If response's status is InProgress, wait a few seconds, then try the same request again.
      operationId: getBillingReportsBillableusage
      produces:
      - application/json
      parameters:
      - name: startDate
        in: query
        description: 'The period start date. Date time is represented as an ISO-8601 string. For example: yyyy-MM-ddTHH:mm:ss[.mmm]Z'
        required: true
        type: string
        format: date-time
      - name: endDate
        in: query
        description: 'The period end date. Date time is represented as an ISO-8601 string. For example: yyyy-MM-ddTHH:mm:ss[.mmm]Z'
        required: true
        type: string
        format: date-time
      responses:
        '200':
          description: successful operation
          schema:
            $ref: '#/definitions/BillingUsageReport'
        '400':
          description: The request could not be understood by the server due to malformed syntax.
          schema:
            $ref: '#/definitions/ErrorBody'
          x-inin-error-codes:
            bad.request: The request could not be understood by the server due to malformed syntax.
            response.entity.too.large: The response is over the size limit. Reduce pageSize or expand list to reduce response size if applicable
            invalid.date: 'Dates must be specified as ISO-8601 strings. For example: yyyy-MM-ddTHH:mm:ss.SSSZ'
            invalid.query.param.value: 'Value [%s] is not valid for parameter [%s]. Allowable values are: %s'
            invalid.property: Value [%s] is not a valid property for object [%s]
            constraint.validation: '%s'
            invalid.value: 'Value [%s] is not valid for field type [%s]. Allowable values are: %s'
        '401':
          description: No authentication bearer token specified in authorization header.
          schema:
            $ref: '#/definitions/ErrorBody'
          x-inin-error-codes:
            authentication.required: No authentication bearer token specified in authorization header.
            ip.not.authorized: 'Requests originating from this IP address are not authorized: [%s]'
            bad.credentials: Invalid login credentials.
        '403':
          description: You are not authorized to perform the requested action.
          schema:
            $ref: '#/definitions/ErrorBody'
          x-inin-error-codes:
            missing.division.permission: Unable to perform the requested action. You are missing the following permission '%s' in the provided division(s).
            app.not.authorized.for.scope: App not authorized to use scope %s
            missing.permissions: 'Unable to perform the requested action. You are missing the following permission(s): %s'
            not.authorized: You are not authorized to perform the requested action.
            missing.any.permissions: 'Unable to perform the requested action. You must have at least one of the following permissions assigned: %s'
            authz.policy.denied: 'Unable to perform the requested action. Your organization''s security policies have denied access. Policy ID(s): [%s]'
            missing.any.division.permissions: 'Unable to perform the requested action. You must have at least one of the following permissions assigned: %s in at least one of the following division(s): %s'
        '404':
          description: The requested resource was not found.
          schema:
            $ref: '#/definitions/ErrorBody'
          x-inin-error-codes:
            not.found: The requested resource was not found.
        '408':
          description: The client did not produce a request within the server timeout limit. This can be caused by a slow network connection and/or large payloads.
          schema:
            $ref: '#/definitions/ErrorBody'
          x-inin-error-codes:
            client.timeout: The client did not produce a request within the server timeout limit. This can be caused by a slow network connection and/or large payloads.
        '409':
          description: The request conflicts with the current state of the target resource.
          schema:
            $ref: '#/definitions/ErrorBody'
          x-inin-error-codes:
            request.conflict: The request conflicts with the current state of the target resource.
        '413':
          description: 'The request is over the size limit. Maximum bytes: %s'
          schema:
            $ref: '#/definitions/ErrorBody'
          x-inin-error-codes:
            request.entity.too.large: 'The request is over the size limit. Maximum bytes: %s'
        '415':
          description: Unsupported Media Type - Unsupported or incorrect media type, such as an incorrect Content-Type value in the header.
          schema:
            $ref: '#/definitions/ErrorBody'
          x-inin-error-codes:
            unsupported.media.type: Unsupported Media Type - Unsupported or incorrect media type, such as an incorrect Content-Type value in the header.
        '429':
          description: Rate limit exceeded the maximum. Retry the request in [%s] seconds
          schema:
            $ref: '#/definitions/ErrorBody'
          x-inin-error-codes:
            too.many.requests.retry.after: Rate limit exceeded the maximum. Retry the request in [%s] seconds
            too.many.requests: Rate limit exceeded the maximum [%s] requests within [%s] seconds
        '500':
          description: The server encountered an unexpected condition which prevented it from fulfilling the request.
          schema:
            $ref: '#/definitions/ErrorBody'
          x-inin-error-codes:
            error: An internal server error occurred.
            internal.server.error: The server encountered an unexpected condition which prevented it from fulfilling the request.
        '503':
          description: Service Unavailable - The server is currently unavailable (because it is overloaded or down for maintenance).
          schema:
            $ref: '#/definitions/ErrorBody'
          x-inin-error-codes:
            service.unavailable: Service Unavailable - The server is currently unavailable (because it is overloaded or down for maintenance).
        '504':
          description: The request timed out.
          schema:
            $ref: '#/definitions/ErrorBody'
          x-inin-error-codes:
            authentication.request.timeout: Authentication request timeout.
            request.timeout: The request timed out.
      security:
      - PureCloud OAuth:
        - billing:readonly
      x-inin-requires-permissions:
        type: ANY
        permissions:
        - billing:subscription:read
        - billing:subscription:view
      x-purecloud-method-name: getBillingReportsBillableusage
  /api/v2/billing/trusteebillingoverview/{trustorOrgId}:
    get:
      tags:
      - Billing
      summary: Get the billing overview for an organization that is managed by a partner.
      description: 'Tax Disclaimer: Prices returned by this API do not include applicable taxes. It is the responsibility of the customer to pay all taxes that are appropriate in their jurisdiction. See the PureCloud API Documentation in the Developer Center for more information about this API: https://developer.mypurecloud.com/api/rest/v2/'
      operationId: getBillingTrusteebillingoverviewTrustorOrgId
      produces:
      - application/json
      parameters:
      - name: billingPeriodIndex
        in: query
        description: 0 for active period (overview data may change until period closes). 1 for prior completed billing period. 2 for two billing cycles prior, and so on.
        required: false
        type: integer
        default: 0
        format: int32
      - name: trustorOrgId
        in: path
        description: The organization ID of the trustor (customer) organization.
        required: true
        type: string
      responses:
        '200':
          description: successful operation
          schema:
            $ref: '#/definitions/TrusteeBillingOverview'
        '400':
          description: The request could not be understood by the server due to malformed syntax.
          schema:
            $ref: '#/definitions/ErrorBody'
          x-inin-error-codes:
            bad.request: The request could not be understood by the server due to malformed syntax.
            response.entity.too.large: The response is over the size limit. Reduce pageSize or expand list to reduce response size if applicable
            invalid.date: 'Dates must be specified as ISO-8601 strings. For example: yyyy-MM-ddTHH:mm:ss.SSSZ'
            invalid.query.param.value: 'Value [%s] is not valid for parameter [%s]. Allowable values are: %s'
            invalid.property: Value [%s] is not a valid property for object [%s]
            constraint.validation: '%s'
            invalid.value: 'Value [%s] is not valid for field type [%s]. Allowable values are: %s'
        '401':
          description: No authentication bearer token specified in authorization header.
          schema:
            $ref: '#/definitions/ErrorBody'
          x-inin-error-codes:
            authentication.required: No authentication bearer token specified in authorization header.
            ip.not.authorized: 'Requests originating from this IP address are not authorized: [%s]'
            bad.credentials: Invalid login credentials.
        '403':
          description: You are not authorized to perform the requested action.
          schema:
            $ref: '#/definitions/ErrorBody'
          x-inin-error-codes:
            missing.division.permission: Unable to perform the requested action. You are missing the following permission '%s' in the provided division(s).
            app.not.authorized.for.scope: App not authorized to use scope %s
            missing.permissions: 'Unable to perform the requested action. You are missing the following permission(s): %s'
            not.authorized: You are not authorized to perform the requested action.
            missing.any.permissions: 'Unable to perform the requested action. You must have at least one of the following permissions assigned: %s'
            authz.policy.denied: 'Unable to perform the requested action. Your organization''s security policies have denied access. Policy ID(s): [%s]'
            missing.any.division.permissions: 'Unable to perform the requested action. You must have at least one of the following permissions assigned: %s in at least one of the following division(s): %s'
        '404':
          description: The requested resource was not found.
          schema:
            $ref: '#/definitions/ErrorBody'
          x-inin-error-codes:
            not.found: The requested resource was not found.
        '408':
          description: The client did not produce a request within the server timeout limit. This can be caused by a slow network connection and/or large payloads.
          schema:
            $ref: '#/definitions/ErrorBody'
          x-inin-error-codes:
            client.timeout: The client did not produce a request within the server timeout limit. This can be caused by a slow network connection and/or large payloads.
        '409':
          description: The request conflicts with the current state of the target resource.
          schema:
            $ref: '#/definitions/ErrorBody'
          x-inin-error-codes:
            request.conflict: The request conflicts with the current state of the target resource.
        '413':
          description: 'The request is over the size limit. Maximum bytes: %s'
          schema:
            $ref: '#/definitions/ErrorBody'
          x-inin-error-codes:
            request.entity.too.large: 'The request is over the size limit. Maximum bytes: %s'
        '415':
          description: Unsupported Media Type - Unsupported or incorrect media type, such as an incorrect Content-Type value in the header.
          schema:
            $ref: '#/definitions/ErrorBody'
          x-inin-error-codes:
            unsupported.media.type: Unsupported Media Type - Unsupported or incorrect media type, such as an incorrect Content-Type value in the header.
        '429':
          description: Rate limit exceeded the maximum. Retry the request in [%s] seconds
          schema:
            $ref: '#/definitions/ErrorBody'
          x-inin-error-codes:
            too.many.requests.retry.after: Rate limit exceeded the maximum. Retry the request in [%s] seconds
            too.many.requests: Rate limit exceeded the maximum [%s] requests within [%s] seconds
        '500':
          description: The server encountered an unexpected condition which prevented it from fulfilling the request.
          schema:
            $ref: '#/definitions/ErrorBody'
          x-inin-error-codes:
            internal.server.error: The server encountered an unexpected condition which prevented it from fulfilling the request.
        '503':
          description: Service Unavailable - The server is currently unavailable (because it is overloaded or down for maintenance).
          schema:
            $ref: '#/definitions/ErrorBody'
          x-inin-error-codes:
            service.unavailable: Service Unavailable - The server is currently unavailable (because it is overloaded or down for maintenance).
        '504':
          description: The request timed out.
          schema:
            $ref: '#/definitions/ErrorBody'
          x-inin-error-codes:
            authentication.request.timeout: Authentication request timeout.
            request.timeout: The request timed out.
      security:
      - PureCloud OAuth:
        - billing
        - billing:readonly
      x-inin-requires-permissions:
        type: ANY
        permissions:
        - affiliateOrganization:clientBilling:view
      x-purecloud-method-name: getBillingTrusteebillingoverviewTrustorOrgId
definitions:
  TrusteeBillingOverview:
    type: object
    required:
    - currency
    - enabledProducts
    - organization
    - subscriptionType
    - usages
    properties:
      id:
        type: string
        description: The globally unique identifier for the object.
        readOnly: true
      name:
        type: string
      organization:
        description: Organization
        $ref: '#/definitions/NamedEntity'
      currency:
        type: string
        description: The currency type.
      enabledProducts:
        type: array
        description: The charge short names for products enabled during the specified period.
        items:
          type: string
      subscriptionType:
        type: string
        description: The subscription type.
        enum:
        - ININ
        - MONTH_TO_MONTH
        - FREE_TRIAL_MONTH_TO_MONTH
        - PREPAY_MONTHLY_COMMITMENT
        - PREPAY
        - DEV_ORG_MONTH_TO_MONTH
        - DEV_ORG_PREPAY_MONTHLY_COMMITMENT
        - DEV_ORG_PREPAY
      rampPeriodStartDate:
        type: string
        format: date-time
        description: 'Date-time the ramp period starts. Date time is represented as an ISO-8601 string. For example: yyyy-MM-ddTHH:mm:ss[.mmm]Z'
      rampPeriodEndDate:
        type: string
        format: date-time
        description: 'Date-time the ramp period ends. Date time is represented as an ISO-8601 string. For example: yyyy-MM-ddTHH:mm:ss[.mmm]Z'
      billingPeriodStartDate:
        type: string
        format: date-time
        description: 'Date-time the billing period started. Date time is represented as an ISO-8601 string. For example: yyyy-MM-ddTHH:mm:ss[.mmm]Z'
      billingPeriodEndDate:
        type: string
        format: date-time
        description: 'Date-time the billing period ended. Date time is represented as an ISO-8601 string. For example: yyyy-MM-ddTHH:mm:ss[.mmm]Z'
      usages:
        type: array
        description: Usages for the specified period.
        items:
          $ref: '#/definitions/SubscriptionOverviewUsage'
      contractAmendmentDate:
        type: string
        format: date-time
        description: 'Date-time the contract was last amended. Date time is represented as an ISO-8601 string. For example: yyyy-MM-ddTHH:mm:ss[.mmm]Z'
      contractEffectiveDate:
        type: string
        format: date-time
        description: 'Date-time the contract became effective. Date time is represented as an ISO-8601 string. For example: yyyy-MM-ddTHH:mm:ss[.mmm]Z'
      contractEndDate:
        type: string
        format: date-time
        description: 'Date-time the contract ends. Date time is represented as an ISO-8601 string. For example: yyyy-MM-ddTHH:mm:ss[.mmm]Z'
      minimumMonthlyAmount:
        type: string
        description: Minimum amount that will be charged for the month
      inRampPeriod:
        type: boolean
      selfUri:
        type: string
        format: uri
        description: The URI for this object
        readOnly: true
  ErrorBody:
    type: object
    properties:
      message:
        type: string
      code:
        type: string
      status:
        type: integer
        format: int32
      entityId:
        type: string
      entityName:
        type: string
      messageWithParams:
        type: string
      messageParams:
        type: object
        additionalProperties:
          type: string
      contextId:
        type: string
      details:
        type: array
        items:
          $ref: '#/definitions/Detail'
      errors:
        type: array
        items:
          $ref: '#/definitions/ErrorBody'
      limit:
        $ref: '#/definitions/Limit'
  NamedEntity:
    type: object
    properties:
      id:
        type: string
        description: The globally unique identifier for the object.
        readOnly: true
      name:
        type: string
        description: The name of the object.
        readOnly: true
  SubscriptionOverviewUsage:
    type: object
    required:
    - grouping
    - name
    - partNumber
    - prepayQuantity
    - unitOfMeasureType
    - usageQuantity
    properties:
      name:
        type: string
        description: Product charge name
      partNumber:
        type: string
        description: Product part number
      grouping:
        type: string
        description: UI grouping key
      unitOfMeasureType:
        type: string
        description: UI unit of measure
      usageQuantity:
        type: string
        description: Usage count for specified period
      overagePrice:
        type: string
        description: Price for usage / overage charge
      prepayQuantity:
        type: string
        description: Items prepaid for specified period
      prepayPrice:
        type: string
        description: Price for prepay charge
      usageNotes:
        type: string
        description: Notes about the usage/charge item
      isCancellable:
        type: boolean
        description: Indicates whether the item is cancellable
      bundleQuantity:
        type: string
        description: Quantity multiplier for this charge
      isThirdParty:
        type: boolean
        description: A charge from a third party entity
  BillingUsageResource:
    type: object
    required:
    - date
    - name
    properties:
      name:
        type: string
        description: Identifies the resource (e.g. license user, device).
      date:
        type: string
        format: date-time
        description: 'The date that the usage was first observed by the billing subsystem. Date time is represented as an ISO-8601 string. For example: yyyy-MM-ddTHH:mm:ss[.mmm]Z'
  BillingUsageReport:
    type: object
    required:
    - endDate
    - startDate
    - usages
    properties:
      id:
        type: string
        description: The globally unique identifier for the object.
        readOnly: true
      name:
        type: string
      startDate:
        type: string
        format: date-time
        description: 'The period start date. Date time is represented as an ISO-8601 string. For example: yyyy-MM-ddTHH:mm:ss[.mmm]Z'
      endDate:
        type: string
        format: date-time
        description: 'The period end date. Date time is represented as an ISO-8601 string. For example: yyyy-MM-ddTHH:mm:ss[.mmm]Z'
      status:
        type: string
        description: Generation status of report
        enum:
        - InProgress
        - Complete
      usages:
        type: array
        description: The usages for the given period.
        items:
          $ref: '#/definitions/BillingUsage'
      selfUri:
        type: string
        format: uri
        description: The URI for this object
        readOnly: true
  BillingUsage:
    type: object
    required:
    - name
    - resources
    - totalUsage
    properties:
      name:
        type: string
        description: Identifies the billable usage.
      totalUsage:
        type: string
        description: The total amount of usage, expressed as a decimal number in string format.
      resources:
        type: array
        description: The resources for which usage was observed (e.g. license users, devices).
        items:
          $ref: '#/definitions/BillingUsageResource'
  Limit:
    type: object
    properties:
      key:
        type: string
      namespace:
        type: string
        enum:
        - web.deployments
        - web.messaging
        - agent.assistant
        - agentic.virtual.agents
        - analytics.agents
        - analytics.alerting
        - analytics.data.extraction
        - analytics
        - analytics.realtime
        - analytics.reporting.settings
        - anomaly.detection
        - architect
        - audiohook
        - audiohook.monitor
        - audit
        - auth.api
        - authorization
        - automation.testing
        - bots
        - bots.voice
        - business.rules
        - callback
        - case.management
        - cobrowse
        - content.management
        - conversation
        - copilot
        - dataactions
        - datatables
        - directory
        - dsar
        - email
        - employee.engagement
        - event.orchestration
        - external.contacts
        - external.events.data.ingestion
        - gamification
        - gcv
        - gdpr
        - groups
        - guides
        - historical.adherence
        - infrastructureascode
        - integrations
        - intent.miner
        - internal.messaging
        - journey
        - knowledge
        - language.understanding
        - learning
        - limit.registry
        - marketplace
        - mcp.analytics.aggregates
        - mcp
        - media.communications
        - messaging
        - micro.frontend
        - multi.org
        - notifications
        - onboarding
        - outbound
        - platform.api
        - predictive.routing
        - presence
        - quality
        - recording
        - response.management
        - routing
        - scim
        - screen.monitoring
        - search
        - secondary.automation.testing
        - skills
        - social.media
        - speech.and.text.analytics
        - speech.integration
        - supportability
        - task.management
        - telephony.configuration
        - usage
        - users
        - users.rules
        - voice.transcription
        - webchat
        - webhooks
        - workforce.management.adherence
        - workforce.management.agent.availability
        - workforce.management.forecast
        - workforce.management
        - workforce.management.scheduling.preferences
        - workforce.management.self.schedule
        - workforce.management.shift.trading
        - system
      value:
        type: integer
        format: int64
  Detail:
    type: object
    properties:
      errorCode:
        type: string
      fieldName:
        type: string
      entityId:
        type: string
      entityName:
        type: string
securityDefinitions:
  PureCloud OAuth:
    type: oauth2
    authorizationUrl: https://login.mypurecloud.com/authorize
    flow: implicit
    scopes:
      all: All the scopes
  Guest Chat JWT:
    type: apiKey
    name: Authorization
    in: header
externalDocs:
  description: PureCloud API Documentation
  url: https://developer.genesys.cloud/