Genesys Billing API

openapi: 3.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/
servers:
- url: https://api.mypurecloud.com
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
      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
        schema:
          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
        schema:
          type: string
          format: date-time
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingUsageReport'
        '400':
          description: The request could not be understood by the server due to malformed syntax.
          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'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
        '401':
          description: No authentication bearer token specified in authorization header.
          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.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
        '403':
          description: You are not authorized to perform the requested action.
          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'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
        '404':
          description: The requested resource was not found.
          x-inin-error-codes:
            not.found: The requested resource was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
        '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.
          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.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
        '409':
          description: The request conflicts with the current state of the target resource.
          x-inin-error-codes:
            request.conflict: The request conflicts with the current state of the target resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
        '413':
          description: 'The request is over the size limit. Maximum bytes: %s'
          x-inin-error-codes:
            request.entity.too.large: 'The request is over the size limit. Maximum bytes: %s'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
        '415':
          description: Unsupported Media Type - Unsupported or incorrect media type, such as an incorrect Content-Type value in the header.
          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.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
        '429':
          description: Rate limit exceeded the maximum. Retry the request in [%s] seconds
          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
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
        '500':
          description: The server encountered an unexpected condition which prevented it from fulfilling the request.
          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.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
        '503':
          description: Service Unavailable - The server is currently unavailable (because it is overloaded or down for maintenance).
          x-inin-error-codes:
            service.unavailable: Service Unavailable - The server is currently unavailable (because it is overloaded or down for maintenance).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
        '504':
          description: The request timed out.
          x-inin-error-codes:
            authentication.request.timeout: Authentication request timeout.
            request.timeout: The request timed out.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
      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
      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
        schema:
          type: integer
          format: int32
          default: 0
      - name: trustorOrgId
        in: path
        description: The organization ID of the trustor (customer) organization.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrusteeBillingOverview'
        '400':
          description: The request could not be understood by the server due to malformed syntax.
          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'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
        '401':
          description: No authentication bearer token specified in authorization header.
          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.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
        '403':
          description: You are not authorized to perform the requested action.
          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'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
        '404':
          description: The requested resource was not found.
          x-inin-error-codes:
            not.found: The requested resource was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
        '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.
          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.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
        '409':
          description: The request conflicts with the current state of the target resource.
          x-inin-error-codes:
            request.conflict: The request conflicts with the current state of the target resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
        '413':
          description: 'The request is over the size limit. Maximum bytes: %s'
          x-inin-error-codes:
            request.entity.too.large: 'The request is over the size limit. Maximum bytes: %s'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
        '415':
          description: Unsupported Media Type - Unsupported or incorrect media type, such as an incorrect Content-Type value in the header.
          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.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
        '429':
          description: Rate limit exceeded the maximum. Retry the request in [%s] seconds
          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
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
        '500':
          description: The server encountered an unexpected condition which prevented it from fulfilling the request.
          x-inin-error-codes:
            internal.server.error: The server encountered an unexpected condition which prevented it from fulfilling the request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
        '503':
          description: Service Unavailable - The server is currently unavailable (because it is overloaded or down for maintenance).
          x-inin-error-codes:
            service.unavailable: Service Unavailable - The server is currently unavailable (because it is overloaded or down for maintenance).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
        '504':
          description: The request timed out.
          x-inin-error-codes:
            authentication.request.timeout: Authentication request timeout.
            request.timeout: The request timed out.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
      security:
      - PureCloud OAuth:
        - billing
        - billing:readonly
      x-inin-requires-permissions:
        type: ANY
        permissions:
        - affiliateOrganization:clientBilling:view
      x-purecloud-method-name: getBillingTrusteebillingoverviewTrustorOrgId
components:
  schemas:
    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: '#/components/schemas/BillingUsageResource'
    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: '#/components/schemas/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: '#/components/schemas/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
    Detail:
      type: object
      properties:
        errorCode:
          type: string
        fieldName:
          type: string
        entityId:
          type: string
        entityName:
          type: string
    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: '#/components/schemas/BillingUsage'
        selfUri:
          type: string
          format: uri
          description: The URI for this 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
    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
    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
    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'
    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: '#/components/schemas/Detail'
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ErrorBody'
        limit:
          $ref: '#/components/schemas/Limit'
  securitySchemes:
    PureCloud_OAuth:
      type: oauth2
      flows:
        implicit:
          scopes:
            all: All the scopes
          authorizationUrl: https://login.mypurecloud.com/authorize
    Guest_Chat_JWT:
      type: apiKey
      name: Authorization
      in: header
externalDocs:
  description: PureCloud API Documentation
  url: https://developer.genesys.cloud/