DoiT Invoices API

openapi: 3.2.0
info:
  title: DoiT Invoices API
  description: Programmatic access to DoiT Platform
  version: v1
servers:
- url: https://api.doit.com
security:
- api_key: []
- tenantId: []
  api_key: []
tags:
- name: Invoices
  description: Access your current and historical billing documents.
paths:
  /billing/v1/invoices:
    get:
      tags:
      - Invoices
      summary: List invoices
      description: 'Returns a list of all the current and historical invoices for your organization.

        Invoices are returned in reverse chronological order by default.'
      operationId: listInvoices
      parameters:
      - name: maxResults
        in: query
        description: The maximum number of results to return in a single page. Leverage the page tokens to iterate through the entire collection.
        schema:
          type: integer
          format: int64
          default: 50
      - $ref: '#/components/parameters/pageToken'
      - name: filter
        in: query
        schema:
          $ref: '#/components/schemas/Filter'
      - name: minCreationTime
        in: query
        description: Min value for the invoice creation time, in milliseconds since the POSIX epoch. If set, only invoices created after or at this timestamp are returned.
        schema:
          type: integer
          format: int64
      - name: maxCreationTime
        in: query
        description: Max value for the invoice creation time, in milliseconds since the POSIX epoch. If set, only invoices created before or at this timestamp are returned.
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: OK - All available invoices returned.
          headers:
            Request-Id:
              $ref: '#/components/headers/RequestId'
            Content-Language:
              $ref: '#/components/headers/ContentLanguage'
          content:
            application/json:
              schema:
                type: object
                properties:
                  invoices:
                    type: array
                    description: Array of Invoices
                    items:
                      $ref: '#/components/schemas/InvoiceListItem'
                  pageToken:
                    type: string
                    description: Page token. Can be used to request the next page of results.
                  rowCount:
                    type: integer
                    description: Invoice rows count
                    format: int64
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /billing/v1/invoices/{id}:
    get:
      tags:
      - Invoices
      summary: Retrieve an invoice
      description: Returns the full details of an invoice specified by the invoice number.
      operationId: getInvoice
      parameters:
      - name: id
        in: path
        description: Invoice number.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK - Invoice details returned.
          headers:
            Request-Id:
              $ref: '#/components/headers/RequestId'
            Content-Language:
              $ref: '#/components/headers/ContentLanguage'
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: Invoice number, identifying the invoice.
                  invoiceDate:
                    type: integer
                    description: The time when this invoice was issued, in milliseconds since the epoch.
                    format: int64
                  platform:
                    $ref: '#/components/schemas/InvoicePlatform'
                  dueDate:
                    type: integer
                    description: The last day to pay the invoice, in milliseconds since the epoch
                    format: int64
                  status:
                    type: string
                    description: Status of the invoice
                    enum:
                    - OPEN
                    - PAST DUE
                    - PAID
                  totalAmount:
                    type: number
                    description: Total invoiced amount
                    format: double
                  balanceAmount:
                    type: number
                    description: Invoice balance to be paid
                    format: double
                  currency:
                    $ref: '#/components/schemas/Currency'
                  url:
                    type: string
                    description: Link to [invoice details page](https://help.doit.com/docs/billing/invoices-and-payments/managing-invoices) in the DoiT console. You can download the PDF invoice from the invoice details page.
                  lineItems:
                    type: array
                    description: Invoice line items.
                    items:
                      $ref: '#/components/schemas/ListItem'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  responses:
    Unauthorized:
      description: Missing or invalid credentials.
      headers:
        WWW-Authenticate:
          description: Bearer challenge per RFC 6750.
          schema:
            type: string
            example: Bearer realm="api.doit.com"
        Request-Id:
          $ref: '#/components/headers/RequestId'
        Content-Language:
          $ref: '#/components/headers/ContentLanguage'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
          example:
            type: https://developer.doit.com/errors/unauthorized
            title: Unauthorized
            status: 401
            detail: missing or invalid bearer token
            instance: https://api.doit.com/requests/req_01HX9P2KQVJ8Z3M4T5N6V7W8Y9
            code: unauthorized
            retryable: false
    NotFound:
      description: The requested resource does not exist.
      headers:
        Request-Id:
          $ref: '#/components/headers/RequestId'
        Content-Language:
          $ref: '#/components/headers/ContentLanguage'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
          example:
            type: https://developer.doit.com/errors/not_found
            title: Resource not found
            status: 404
            detail: organization not found
            instance: https://api.doit.com/requests/req_01HX9P2KQVJ8Z3M4T5N6V7W8Y9
            code: not_found
            retryable: false
    BadRequest:
      description: Syntactically malformed request, missing required parameter, or unsupported parameter value.
      headers:
        Request-Id:
          $ref: '#/components/headers/RequestId'
        Content-Language:
          $ref: '#/components/headers/ContentLanguage'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
          examples:
            validationFailed:
              summary: Missing or invalid parameter
              value:
                type: https://developer.doit.com/errors/validation_failed
                title: Validation failed
                status: 400
                detail: The request is missing a required parameter or contains an invalid value.
                instance: https://api.doit.com/requests/req_01HX9P2KQVJ8Z3M4T5N6V7W8Y9
                code: validation_failed
                retryable: false
            tenantIdRequired:
              summary: Tenant scope not resolvable
              value:
                type: https://developer.doit.com/errors/tenant_id_required
                title: Tenant ID required
                status: 400
                detail: X-Tenant-Id header is required when the credential can access more than one tenant.
                instance: https://api.doit.com/requests/req_01HX9P2KQVJ8Z3M4T5N6V7W8Y9
                code: tenant_id_required
                retryable: false
            tenantIdMismatch:
              summary: Header conflicts with the key's tenant
              value:
                type: https://developer.doit.com/errors/tenant_id_mismatch
                title: Tenant ID mismatch
                status: 400
                detail: X-Tenant-Id does not match the tenant the credential is scoped to.
                instance: https://api.doit.com/requests/req_01HX9P2KQVJ8Z3M4T5N6V7W8Y9
                code: tenant_id_mismatch
                retryable: false
            gcpServiceRequired:
              summary: GCP region filter without commitment type
              value:
                type: https://developer.doit.com/errors/gcp_service_required
                title: GCP service required
                status: 400
                detail: The region query parameter requires gcp_service.
                instance: https://api.doit.com/requests/req_01HX9P2KQVJ8Z3M4T5N6V7W8Y9
                code: gcp_service_required
                retryable: false
            paginationTokenInvalid:
              summary: Structurally invalid pagination cursor
              value:
                type: https://developer.doit.com/errors/pagination_token_invalid
                title: Invalid pagination token
                status: 400
                detail: The pageToken cursor is structurally invalid (decode failure or tampering).
                instance: https://api.doit.com/requests/req_01HX9P2KQVJ8Z3M4T5N6V7W8Y9
                code: pagination_token_invalid
                retryable: false
            paginationTokenExpired:
              summary: Expired pagination cursor
              value:
                type: https://developer.doit.com/errors/pagination_token_expired
                title: Expired pagination token
                status: 400
                detail: The pageToken cursor is no longer valid; restart pagination from the beginning.
                instance: https://api.doit.com/requests/req_01HX9P2KQVJ8Z3M4T5N6V7W8Y9
                code: pagination_token_expired
                retryable: false
    InternalServerError:
      description: Unexpected server error.
      headers:
        Request-Id:
          $ref: '#/components/headers/RequestId'
        Content-Language:
          $ref: '#/components/headers/ContentLanguage'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
          example:
            type: https://developer.doit.com/errors/internal_error
            title: Internal server error
            status: 500
            detail: an unexpected error occurred
            instance: https://api.doit.com/requests/req_01HX9P2KQVJ8Z3M4T5N6V7W8Y9
            code: internal_error
            retryable: true
    Forbidden:
      description: Authenticated but not authorized to perform this request.
      headers:
        Request-Id:
          $ref: '#/components/headers/RequestId'
        Content-Language:
          $ref: '#/components/headers/ContentLanguage'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
          example:
            type: https://developer.doit.com/errors/forbidden
            title: Forbidden
            status: 403
            detail: caller does not have permission to access this customer's commitments
            instance: https://api.doit.com/requests/req_01HX9P2KQVJ8Z3M4T5N6V7W8Y9
            code: forbidden
            retryable: false
  headers:
    RequestId:
      description: DoiT request identifier for support and log correlation. Format `req_<ULID>`.
      schema:
        type: string
        pattern: ^req_[0-9A-HJKMNP-TV-Z]{26}$
        example: req_01HX9P2KQVJ8Z3M4T5N6V7W8Y9
    ContentLanguage:
      description: Language of the response body. Always `en` for this API.
      schema:
        type: string
        enum:
        - en
  schemas:
    ListItem:
      type: object
      description: Invoice line item.
      properties:
        currency:
          type: string
        description:
          type: string
        details:
          type: string
        price:
          type: number
          format: double
        qty:
          type: number
          format: double
        type:
          type: string
    ProblemDetails:
      type: object
      required:
      - type
      - title
      - status
      - detail
      - instance
      - code
      - retryable
      additionalProperties: true
      description: RFC 9457 Problem Details — standard DoiT error envelope for all non-2xx responses.
      properties:
        type:
          type: string
          format: uri
          example: https://developer.doit.com/errors/not_found
        title:
          type: string
          example: Resource not found
        status:
          type: integer
          example: 404
        detail:
          type: string
          example: customer not found
        instance:
          type: string
          format: uri
          example: https://api.doit.com/requests/req_01HX9P2KQVJ8Z3M4T5N6V7W8Y9
        code:
          type: string
          pattern: ^([a-z][a-z0-9_]*|[a-z][a-z0-9]*(?:-[a-z0-9]+)*\.[a-z][a-z0-9_]*)$
          example: not_found
        retryable:
          type: boolean
          example: false
        details:
          type: array
          items:
            type: object
            required:
            - issue
            properties:
              issue:
                type: string
                pattern: ^[a-z][a-z0-9_]*$
              field:
                type: string
            additionalProperties: true
        docsUrl:
          type:
          - string
          - 'null'
          format: uri
    Filter:
      type: string
      description: An expression for filtering the results. The syntax is `key:[<value>]`. Multiple filters can be connected using a pipe |. See [Filters](https://developer.doit.com/docs/filters).
    Currency:
      description: Currency code for monetary values.
      type: string
      enum:
      - USD
      - ILS
      - EUR
      - AUD
      - CAD
      - GBP
      - DKK
      - NOK
      - SEK
      - BRL
      - SGD
      - MXN
      - CHF
      - MYR
      - TWD
      - EGP
      - ZAR
      - JPY
      - IDR
      - AED
      - THB
      - COP
    InvoiceListItem:
      type: object
      description: Summary information about an invoice.
      properties:
        id:
          type: string
          description: Invoice number, identifying the invoice.
        invoiceDate:
          type: integer
          description: The time when this invoice was issued, in milliseconds since the epoch.
          format: int64
        platform:
          $ref: '#/components/schemas/InvoicePlatform'
        dueDate:
          type: integer
          description: The last day to pay the invoice, in milliseconds since the epoch
          format: int64
        status:
          type: string
          description: Status of the invoice
          enum:
          - OPEN
          - PAST DUE
          - PAID
        totalAmount:
          type: number
          description: Total invoiced amount
          format: double
        balanceAmount:
          type: number
          description: Invoice balance to be paid
          format: double
        currency:
          $ref: '#/components/schemas/Currency'
        url:
          type: string
          description: Link to [invoice details page](https://help.doit.com/docs/billing/invoices-and-payments/managing-invoices) in the DoiT console. You can download the PDF invoice from the invoice details page.
    InvoicePlatform:
      type: string
      description: Platform identifier for invoice source.
      enum:
      - google-cloud
      - amazon-web-services
      - microsoft-azure
      - g-suite
      - office-365
      - superquery
      - looker
      - navigator
      - solve
  parameters:
    pageToken:
      name: pageToken
      in: query
      description: Page token, returned by a previous call, to request the next page of results
      schema:
        type: string
  securitySchemes:
    api_key:
      type: apiKey
      name: Authorization
      description: Use the "Bearer <API_KEY>" format or sign in for autofill
      in: header
    tenantId:
      type: apiKey
      name: X-Tenant-Id
      description: 'Customer (tenant) ID for the request. Separate from your API token: always authenticate with `Authorization: Bearer <token>` (personal or service account). See [Get Started](https://developer.doit.com/docs/start). Omit when your token is scoped to a single customer (resolved automatically). A service account can select an active direct or nested descendant of its home customer; the endpoint''s normal permissions, entitlements, and resource-ownership checks still apply. A service-account target outside that customer subtree returns `403 Forbidden`. Prefer this header over the legacy `customerContext` query parameter, which only applies to legacy API keys and is ignored by personal and service account tokens.'
      in: header
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://console.doit.com/sign-in/oauth
          tokenUrl: https://console.doit.com/api/auth/token
          scopes:
            dci: Access All Data
x-samples-languages:
- curl
- go
- node
- python
x-cli-config:
  security: oauth2
  params:
    client_id: cli
x-provenance:
  method: harvested
  publisher: DoiT
  source: https://api.doit.com/openapi.yaml
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)