APIs.io Engineering Platform Billing API

openapi: 3.2.0
info:
  title: Engineering Platform Billing API
  x-refined-note:
  - x-github-plan differs across the merged source definitions and was not carried
  - x-github-release differs across the merged source definitions and was not carried
  version: '1.0'
  description: 'Operations tagged Billing across 2 of this provider''s published API definitions: github-openapi-original.yml, postman-openapi-original.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: '{protocol}://{hostname}/api/v3'
  variables:
    hostname:
      description: Self-hosted Enterprise Server hostname
      default: HOSTNAME
    protocol:
      description: Self-hosted Enterprise Server protocol
      default: http
- url: https://api.getpostman.com
- url: https://api.eu.postman.com
tags:
- name: Billing
  description: Monitor charges and usage from Actions and Packages.
paths:
  /enterprises/{enterprise}/settings/billing/advanced-security:
    get:
      summary: APIs.io Engineering Platform Get GitHub Advanced Security active committers for an enterprise
      description: 'Gets the GitHub Advanced Security active committers for an enterprise per repository.


        Each distinct user login across all repositories is counted as a single Advanced Security seat, so the `total_advanced_security_committers` is not the sum of active_users for each repository.


        The total number of repositories with committer information is tracked by the `total_count` field.'
      tags:
      - Billing
      operationId: billing/get-github-advanced-security-billing-ghe
      externalDocs:
        description: API method documentation
        url: https://docs.github.com/enterprise-server@3.9/rest/enterprise-admin/billing#get-github-advanced-security-active-committers-for-an-enterprise
      parameters:
      - $ref: '#/components/parameters/enterprise'
      - $ref: '#/components/parameters/per-page'
      - $ref: '#/components/parameters/page'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/advanced-security-active-committers'
              examples:
                default:
                  $ref: '#/components/examples/advanced-security-active-committers'
        '403':
          $ref: '#/components/responses/code_scanning_forbidden_read'
      x-github:
        githubCloudOnly: true
        enabledForGitHubApps: false
        category: enterprise-admin
        subcategory: billing
    servers:
    - url: '{protocol}://{hostname}/api/v3'
      variables:
        hostname:
          description: Self-hosted Enterprise Server hostname
          default: HOSTNAME
        protocol:
          description: Self-hosted Enterprise Server protocol
          default: http
  /orgs/{org}/settings/billing/advanced-security:
    get:
      summary: APIs.io Engineering Platform Get GitHub Advanced Security active committers for an organization
      description: 'Gets the GitHub Advanced Security active committers for an organization per repository.


        Each distinct user login across all repositories is counted as a single Advanced Security seat, so the `total_advanced_security_committers` is not the sum of advanced_security_committers for each repository.


        If this organization defers to an enterprise for billing, the `total_advanced_security_committers` returned from the organization API may include some users that are in more than one organization, so they will only consume a single Advanced Security seat at the enterprise level.


        The total number of repositories with committer information is tracked by the `total_count` field.'
      tags:
      - Billing
      operationId: billing/get-github-advanced-security-billing-org
      externalDocs:
        description: API method documentation
        url: https://docs.github.com/enterprise-server@3.9/rest/billing/billing#get-github-advanced-security-active-committers-for-an-organization
      parameters:
      - $ref: '#/components/parameters/org'
      - $ref: '#/components/parameters/per-page'
      - $ref: '#/components/parameters/page'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/advanced-security-active-committers'
              examples:
                default:
                  $ref: '#/components/examples/advanced-security-active-committers'
        '403':
          $ref: '#/components/responses/code_scanning_forbidden_read'
      x-github:
        githubCloudOnly: true
        enabledForGitHubApps: true
        category: billing
        subcategory: billing
    servers:
    - url: '{protocol}://{hostname}/api/v3'
      variables:
        hostname:
          description: Self-hosted Enterprise Server hostname
          default: HOSTNAME
        protocol:
          description: Self-hosted Enterprise Server protocol
          default: http
  /accounts:
    get:
      summary: APIs.io Engineering Platform Get accounts
      description: Gets Postman billing account details for the given team.
      operationId: getAccounts
      tags:
      - Billing
      responses:
        '200':
          $ref: '#/components/responses/getAccounts'
        '400':
          $ref: '#/components/responses/invoicesNoTeam400Error'
        '401':
          $ref: '#/components/responses/unauthorizedError'
        '500':
          $ref: '#/components/responses/common500ErrorServerError'
      security:
      - PostmanApiKey: []
      - scimApiKey: []
    servers:
    - url: https://api.getpostman.com
    - url: https://api.eu.postman.com
  /accounts/{accountId}/invoices:
    get:
      summary: APIs.io Engineering Platform List account invoices
      description: Gets all invoices for a Postman billing account filtered by the status of the invoice.
      operationId: getAccountInvoices
      tags:
      - Billing
      responses:
        '200':
          $ref: '#/components/responses/getAccountInvoices'
        '400':
          $ref: '#/components/responses/invoiceMissingStatus400Error'
        '401':
          $ref: '#/components/responses/unauthorizedError'
        '403':
          $ref: '#/components/responses/invoicesForbidden403Error'
        '500':
          $ref: '#/components/responses/common500ErrorServerError'
      parameters:
      - $ref: '#/components/parameters/billingAccountId'
      - $ref: '#/components/parameters/billingAccountStatus'
      security:
      - PostmanApiKey: []
      - scimApiKey: []
    servers:
    - url: https://api.getpostman.com
    - url: https://api.eu.postman.com
components:
  parameters:
    org:
      name: org
      description: The organization name. The name is not case sensitive.
      in: path
      required: true
      schema:
        type: string
    per-page:
      name: per_page
      description: The number of results per page (max 100). For more information, see "[Using pagination in the REST API](https://docs.github.com/enterprise-server@3.9/rest/using-the-rest-api/using-pagination-in-the-rest-api)."
      in: query
      schema:
        type: integer
        default: 30
    enterprise:
      name: enterprise
      description: The slug version of the enterprise name. You can also substitute this value with the enterprise id.
      in: path
      required: true
      schema:
        type: string
    page:
      name: page
      description: The page number of the results to fetch. For more information, see "[Using pagination in the REST API](https://docs.github.com/enterprise-server@3.9/rest/using-the-rest-api/using-pagination-in-the-rest-api)."
      in: query
      schema:
        type: integer
        default: 1
    billingAccountStatus:
      name: status
      in: query
      required: true
      description: The account's status.
      schema:
        type: string
        enum:
        - PAID
        example: PAID
    billingAccountId:
      name: accountId
      in: path
      required: true
      description: The account's ID.
      schema:
        type: string
        example: '123456'
  responses:
    code_scanning_forbidden_read:
      description: Response if GitHub Advanced Security is not enabled for this repository
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/basic-error'
    invoicesForbidden403Error:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/invoicesForbidden403Error'
          example:
            type: https://api.postman.com/problems/forbidden
            title: Forbidden
            status: 403
            detail: You are not authorized to perform this action
    getAccounts:
      description: Successful Response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/invoicesAccountInfo'
          example:
            billingEmail: taylor.lee@example.com
            id: 372691
            salesChannel: SELF_SERVE
            slots:
              available: 8
              consumed: 2
              total: 10
              unbilled: 0
            state: PAID
            teamId: 380691
    common500ErrorServerError:
      description: Internal Server Error
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: object
                properties:
                  name:
                    type: string
                    description: The error name.
                    example: serverError
                  message:
                    type: string
                    description: The error message.
                    example: An error has occurred on the server.
          example:
            error:
              name: serverError
              message: An error has occurred on the server.
    invoiceMissingStatus400Error:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/invoiceMissingStatus400Error'
          example:
            type: https://api.postman.com/problems/bad-request
            title: Malformed request
            status: 400
            detail: Please provide a valid status to fetch invoices
    getAccountInvoices:
      description: Successful Response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/getAccountInvoices'
          example:
            data:
            - id: inv_7UDSYBJPGQU93N7M
              status: PAID
              issuedAt: '2023-10-12'
              totalAmount:
                value: 440
                currency: USD
              links:
                web:
                  href: https://pay.postman.com/invoices/pay?invoice_public_id=inv_7UDSYBJPGQU93N7M
    unauthorizedError:
      description: Unauthorized
      content:
        application/problem+json:
          schema:
            type: object
            properties:
              type:
                type: string
                format: uri-reference
                description: The [URI reference](https://www.rfc-editor.org/rfc/rfc3986) that identifies the type of problem.
                example: https://api.postman.com/problems/unauthorized
              title:
                type: string
                description: A short summary of the problem.
                example: Unauthorized
              detail:
                type: string
                description: Information about the error.
                example: An API key must be provided in the request header or query string
              status:
                type: number
                format: http-status-code
                description: The error's HTTP status code.
                example: 401
          example:
            type: https://api.postman.com/problems/unauthorized
            title: Unauthorized
            detail: An API key must be provided in the request header or query string
            status: 401
    invoicesNoTeam400Error:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/invoicesNoTeam400Error'
          example:
            type: https://api.postman.com/problems/bad-request
            title: Malformed request
            status: 400
            detail: You must be part of a team
  schemas:
    advanced-security-active-committers:
      type: object
      properties:
        total_advanced_security_committers:
          type: integer
          example: 25
        total_count:
          type: integer
          example: 2
        repositories:
          type: array
          items:
            $ref: '#/components/schemas/advanced-security-active-committers-repository'
      required:
      - repositories
    advanced-security-active-committers-user:
      type: object
      properties:
        user_login:
          type: string
        last_pushed_date:
          type: string
          example: '2021-11-03'
      required:
      - user_login
      - last_pushed_date
    advanced-security-active-committers-repository:
      type: object
      properties:
        name:
          type: string
          example: octocat/Hello-World
        advanced_security_committers:
          type: integer
          example: 25
        advanced_security_committers_breakdown:
          type: array
          items:
            $ref: '#/components/schemas/advanced-security-active-committers-user'
      required:
      - name
      - advanced_security_committers
      - advanced_security_committers_breakdown
    basic-error:
      title: Basic Error
      description: Basic Error
      type: object
      properties:
        message:
          type: string
        documentation_url:
          type: string
        url:
          type: string
        status:
          type: string
    invoiceMissingStatus400Error:
      title: Missing Status
      type: object
      properties:
        type:
          type: string
          format: uri
          description: The error type.
          example: https://api.postman.com/problems/bad-request
        title:
          type: string
          description: A short summary of the error.
          example: Malformed request
        status:
          type: number
          format: http-status-code
          description: The error's HTTP status code.
          example: 400
        detail:
          type: string
          description: Details about the occurrence of the error.
          example: Please provide a valid status to fetch invoices
    invoiceData:
      title: Account Invoice
      type: object
      description: Information about the invoice.
      properties:
        id:
          type: string
          description: The invoice's ID.
          example: inv_7UDSYBJPGQU93N7M
        status:
          type: string
          description: The invoice's status.
          example: PAID
        issuedAt:
          type: string
          format: date
          description: The date on which the invoice was issued.
          example: '2023-10-12'
        totalAmount:
          type: object
          description: Information about the invoice's total billed amount.
          properties:
            value:
              type: integer
              description: The amount billed.
              example: 440
            currency:
              type: string
              description: The currency of the billed amount. Currently only supports the `USD` value.
              example: USD
        links:
          type: object
          description: A [JSON API spec](https://jsonapi.org/format/#document-links) object containing hypermedia links.
          properties:
            web:
              type: object
              description: An object containing web-based account references.
              properties:
                href:
                  type: string
                  format: url
                  description: A URL where you can download the invoice in PDF and view details.
                  example: https://pay.postman.com/invoices/pay?invoice_public_id=inv_7UDSYBJPGQU93N7M
    invoicesForbidden403Error:
      title: Forbidden
      type: object
      properties:
        type:
          type: string
          format: uri
          description: The error type.
          example: https://api.postman.com/problems/forbidden
        title:
          type: string
          description: A short summary of the error.
          example: Forbidden
        status:
          type: number
          format: http-status-code
          description: The error's HTTP status code.
          example: 403
        detail:
          type: string
          description: Details about the occurrence of the error.
          example: You are not authorized to perform this action
    getAccountInvoices:
      type: object
      required:
      - data
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/invoiceData'
    invoicesNoTeam400Error:
      title: Bad Request
      type: object
      properties:
        type:
          type: string
          format: uri
          description: The error type.
          example: https://api.postman.com/problems/bad-request
        title:
          type: string
          description: A short summary of the error.
          example: Malformed request
        status:
          type: number
          format: http-status-code
          description: The error's HTTP status code.
          example: 400
        detail:
          type: string
          description: Details about the occurrence of the error.
          example: You must be part of a team
    invoicesAccountInfo:
      title: Account Information
      type: object
      description: Information about the account.
      properties:
        billingEmail:
          type: string
          format: email
          description: The email address to which invoices are sent.
          example: taylor.lee@example.com
        id:
          type: integer
          description: The account's ID.
          example: 12345678
        state:
          type: string
          description: 'The account''s current state:

            - `FREE`

            - `PAID`

            - `EXPIRED_TRIAL`

            - `OVERDUE`

            - `SUSPENDED`

            - `BLOCKED`

            - `PAYMENT_DISPUTED`

            '
          example: PAID
        teamId:
          type: integer
          description: The team's ID associated with the account.
          example: 1234
        salesChannel:
          type: string
          description: 'The sales channel from which the account was created:

            - `SELF_SERVE` — The user purchased the account plan.

            - `SALES_SERVE` — The account was purchased through the Postman sales team process.

            '
          enum:
          - SELF_SERVE
          - SALES_SERVE
          example: SELF_SERVE
        slots:
          type: object
          description: Information about the team's slots.
          properties:
            available:
              type: integer
              description: The number of the team's available slots.
              example: 8
            consumed:
              type: integer
              description: The number of currently-billed team members.
              example: 2
            total:
              type: integer
              description: The total number of slots available to the team.
              example: 10
            unbilled:
              type: integer
              description: The number of unbilled slots if [auto-flex billing](https://learning.postman.com/auto-flex-policy/) is available.
              example: 0
  examples:
    advanced-security-active-committers:
      value:
        total_advanced_security_committers: 2
        total_count: 2
        repositories:
        - name: octocat-org/Hello-World
          advanced_security_committers: 2
          advanced_security_committers_breakdown:
          - user_login: octocat
            last_pushed_date: '2021-11-03'
          - user_login: octokitten
            last_pushed_date: '2021-10-25'
        - name: octocat-org/server
          advanced_security_committers: 1
          advanced_security_committers_breakdown:
          - user_login: octokitten
            last_pushed_date: '2021-10-26'
  securitySchemes:
    PostmanApiKey:
      type: apiKey
      in: header
      name: x-api-key
    scimApiKey:
      type: apiKey
      in: header
      name: Authorization
      description: A valid [SCIM API key](https://learning.postman.com/docs/administration/scim-provisioning/scim-provisioning-overview/#generating-scim-api-key) for calls to SCIM endpoints.
externalDocs:
  description: GitHub Enterprise Developer Docs
  url: https://docs.github.com/enterprise-server@3.9/rest/
x-refined-from:
- github-openapi-original.yml
- postman-openapi-original.yml
x-hasEquivalentPaths: true