Billing insights endpoint documentation (#1121)

Author: k8abyte

specification/resources/billing/billingInsights_list.yml

@@ -0,0 +1,47 @@
+operationId: billingInsights_list
+
+summary: List Billing Insights
+
+description: >-
+
+  This endpoint returns day-over-day changes in billing resource usage based on nightly invoice items, including total amount, region, SKU, and description for a specified date range. It is important to note that the daily resource usage may not reflect month-end billing totals when totaled for a given month as nightly invoice items do not necessarily encompass all invoicing factors for the entire month.
+
+tags:
+  - Billing
+
+parameters:
+  - $ref: 'parameters.yml#/account_urn'
+  - $ref: 'parameters.yml#/start_date'
+  - $ref: 'parameters.yml#/end_date'
+  - $ref: '../../shared/parameters.yml#/per_page'
+  - $ref: '../../shared/parameters.yml#/page'
+
+responses:
+  '200':
+    $ref: 'responses/billing_insights.yml'
+
+  '401':
+    $ref: '../../shared/responses/unauthorized.yml'
+
+  '403':
+    $ref: '../../shared/responses/forbidden.yml'
+
+  '404':
+    $ref: '../../shared/responses/not_found.yml'
+
+  '429':
+    $ref: '../../shared/responses/too_many_requests.yml'
+
+  '500':
+    $ref: '../../shared/responses/server_error.yml'
+
+  default:
+    $ref: '../../shared/responses/unexpected_error.yml'
+
+x-codeSamples:
+  - $ref: 'examples/curl/billingInsights_list.yml'
+  - $ref: 'examples/python/billingInsights_list.yml'
+
+security:
+  - bearer_auth:
+    - 'billing:read'

specification/resources/billing/examples/curl/billingInsights_list.yml

@@ -0,0 +1,6 @@
+lang: cURL
+source: |-
+  curl -X GET \
+    -H "Content-Type: application/json" \
+    -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
+    "https://api.digitalocean.com/v2/billing/do:team:12345678-1234-1234-1234-123456789012/insights/2025-01-01/2025-01-31?per_page=20&page=1"

specification/resources/billing/examples/python/billingInsights_list.yml

@@ -0,0 +1,14 @@
+lang: Python
+source: |-
+  import os
+  from pydo import Client
+
+  client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN"))
+
+  insights = client.billing.list_insights(
+      account_urn="do:team:12345678-1234-1234-1234-123456789012",
+      start_date="2025-01-01",
+      end_date="2025-01-31",
+      page_size=100,
+      page_number=1
+  )

specification/resources/billing/models/billing_data_point.yml

@@ -0,0 +1,38 @@
+type: object
+
+properties:
+  usage_team_urn:
+    type: string
+    description: URN of the team that incurred the usage
+    example: 'do:team:12345678-1234-1234-1234-123456789012'
+
+  start_date:
+    type: string
+    format: date
+    description: Start date of the billing data point in YYYY-MM-DD format
+    example: '2025-01-15'
+
+  total_amount:
+    type: string
+    description: Total amount for this data point in USD
+    example: '12.45'
+
+  region:
+    type: string
+    description: Region where the usage occurred
+    example: 'nyc3'
+
+  sku:
+    type: string
+    description: Unique SKU identifier for the billed resource
+    example: '1-DO-DROP-0109'
+
+  description:
+    type: string
+    description: Description of the billed resource or service as shown on an invoice item
+    example: 'droplet name (c-2-4GiB)'
+
+  group_description:
+    type: string
+    description: Optional invoice item group name of the billed resource or service, blank when not part an invoice item group
+    example: 'kubernetes cluster name'

specification/resources/billing/parameters.yml

@@ -5,4 +5,33 @@ invoice_uuid:
   schema:
     type: string
   example: 22737513-0ea7-4206-8ceb-98a575af7681
-  required: true
+  required: true
+
+account_urn:
+  name: account_urn
+  description: URN of the customer account, can be a team (do:team:uuid) or an organization (do:teamgroup:uuid)
+  in: path
+  schema:
+    type: string
+  example: do:team:12345678-1234-1234-1234-123456789012
+  required: true
+
+start_date:
+  name: start_date
+  description: Start date for billing insights in YYYY-MM-DD format
+  in: query
+  schema:
+    type: string
+    format: date
+  example: '2025-01-01'
+  required: true
+
+end_date:
+  name: end_date
+  description: End date for billing insights in YYYY-MM-DD format. Must be within 31 days of start_date
+  in: query
+  schema:
+    type: string
+    format: date
+  example: '2025-01-31'
+  required: true

specification/resources/billing/responses/billing_insights.yml

@@ -0,0 +1,64 @@
+description: >-
+  The response will be a JSON object that contains a list of billing data points
+  under the `data_points` key, along with pagination metadata including
+  `total_items`, `total_pages`, and `current_page`.
+
+headers:
+  ratelimit-limit:
+    $ref: '../../../shared/headers.yml#/ratelimit-limit'
+  ratelimit-remaining:
+    $ref: '../../../shared/headers.yml#/ratelimit-remaining'
+  ratelimit-reset:
+    $ref: '../../../shared/headers.yml#/ratelimit-reset'
+
+content:
+  application/json:
+    schema:
+      type: object
+      properties:
+        data_points:
+          type: array
+          description: Array of billing data points, which are day-over-day changes in billing resource usage based on nightly invoice item estimates, for the requested period
+          items:
+            $ref: '../models/billing_data_point.yml'
+
+        total_items:
+          type: integer
+          description: Total number of items available across all pages
+          example: 250
+
+        total_pages:
+          type: integer
+          description: Total number of pages available
+          example: 3
+
+        current_page:
+          type: integer
+          description: Current page number
+          example: 1
+
+      required:
+        - data_points
+        - total_items
+        - total_pages
+        - current_page
+
+    example:
+      data_points:
+        - usage_team_urn: 'do:team:12345678-1234-1234-1234-123456789012'
+          start_date: '2025-01-01'
+          total_amount: '0.86'
+          region: 'nyc3'
+          sku: '1-DO-DROP-0109'
+          description: 'droplet name (c-2-4GiB)'
+          group_description: ''
+        - usage_team_urn: 'do:team:12345678-1234-1234-1234-123456789012'
+          start_date: '2025-01-01'
+          total_amount: '2.57'
+          region: 'nyc3'
+          sku: '1-KS-K8SWN-00109'
+          description: '3 nodes - 4 GB / 2 vCPU / 80 GB SSD'
+          group_description: 'kubernetes cluster name'
+      total_items: 2
+      total_pages: 1
+      current_page: 1