Billing insights endpoint documentation added to public with related minor fixes (#1123)

Author: k8abyte

specification/DigitalOcean-public.v2.yaml

@@ -70,8 +70,8 @@ tags:
 
   - name: Billing
     description: |-
-      The billing endpoints allow you to retrieve your account balance, invoices
-      and billing history.
+      The billing endpoints allow you to retrieve your account balance, invoices, 
+      billing history, and insights.
 
       **Balance:** By sending requests to the `/v2/customers/my/balance` endpoint, you can
       retrieve the balance information for the requested customer account.
@@ -88,6 +88,14 @@ tags:
       issued, or credits granted. To interact with invoices, you
       will generally send requests to the invoices endpoint at
       `/v2/customers/my/billing_history`.
+      
+      **Billing Insights:** 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.
+        `v2/billing/{account_urn}/insights/{start_date}/{end_date}` where account_urn is the URN of the customer 
+      account, can be a team (do:team:uuid) or an organization (do:teamgroup:uuid). The date range specified by 
+      start_date and end_date must be in YYYY-MM-DD format.
 
   - name: Block Storage
     description: |-
@@ -831,6 +839,10 @@ paths:
     get:
       $ref: "resources/billing/invoices_get_summaryByUUID.yml"
 
+  /v2/billing/{account_urn}/insights/{start_date}/{end_date}:
+    get:
+      $ref: "resources/billing/billingInsights_list.yml"
+
   /v2/databases/options:
     get:
       $ref: "resources/databases/databases_list_options.yml"

specification/resources/billing/billingInsights_list.yml

@@ -4,7 +4,7 @@ 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.
+  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 item estimates do not necessarily encompass all invoicing factors for the entire month.
 
 tags:
   - Billing
@@ -23,9 +23,6 @@ responses:
   '401':
     $ref: '../../shared/responses/unauthorized.yml'
 
-  '403':
-    $ref: '../../shared/responses/forbidden.yml'
-
   '404':
     $ref: '../../shared/responses/not_found.yml'
 

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

@@ -9,6 +9,6 @@ source: |-
       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
+      per_page=100,
+      page=1
   )

specification/resources/billing/parameters.yml

@@ -19,7 +19,7 @@ account_urn:
 start_date:
   name: start_date
   description: Start date for billing insights in YYYY-MM-DD format
-  in: query
+  in: path
   schema:
     type: string
     format: date
@@ -29,7 +29,7 @@ start_date:
 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
+  in: path
   schema:
     type: string
     format: date