feat(billing): add usage.get method, update usage.paygo endpoint

vaishakdinesh · vaishakdinesh · commit 665f6ea2ab4a · 2026-05-21T09:01:21.000-07:00
diff --git a/src/resources/billing/api.md b/src/resources/billing/api.md
@@ -14,8 +14,10 @@ Methods:
 
 Types:
 
+- <code><a href="./src/resources/billing/usage.ts">UsageGetResponse</a></code>
 - <code><a href="./src/resources/billing/usage.ts">UsagePaygoResponse</a></code>
 
 Methods:
 
-- <code title="get /accounts/{account_id}/billing/usage/paygo">client.billing.usage.<a href="./src/resources/billing/usage.ts">paygo</a>({ ...params }) -> UsagePaygoResponse</code>
+- <code title="get /accounts/{account_id}/billable/usage">client.billing.usage.<a href="./src/resources/billing/usage.ts">get</a>({ ...params }) -> UsageGetResponse</code>
+- <code title="get /accounts/{account_id}/paygo-usage">client.billing.usage.<a href="./src/resources/billing/usage.ts">paygo</a>({ ...params }) -> UsagePaygoResponse</code>
diff --git a/src/resources/billing/billing.ts b/src/resources/billing/billing.ts
@@ -4,7 +4,7 @@ import { APIResource } from '../../resource';
 import * as ProfilesAPI from './profiles';
 import { ProfileGetParams, ProfileGetResponse, Profiles } from './profiles';
 import * as UsageAPI from './usage';
-import { Usage, UsagePaygoParams, UsagePaygoResponse } from './usage';
+import { Usage, UsageGetParams, UsageGetResponse, UsagePaygoParams, UsagePaygoResponse } from './usage';
 
 export class Billing extends APIResource {
   profiles: ProfilesAPI.Profiles = new ProfilesAPI.Profiles(this._client);
@@ -23,7 +23,9 @@ export declare namespace Billing {
 
   export {
     Usage as Usage,
+    type UsageGetResponse as UsageGetResponse,
     type UsagePaygoResponse as UsagePaygoResponse,
+    type UsageGetParams as UsageGetParams,
     type UsagePaygoParams as UsagePaygoParams,
   };
 }
diff --git a/src/resources/billing/index.ts b/src/resources/billing/index.ts
@@ -2,4 +2,10 @@
 
 export { Billing } from './billing';
 export { Profiles, type ProfileGetResponse, type ProfileGetParams } from './profiles';
-export { Usage, type UsagePaygoResponse, type UsagePaygoParams } from './usage';
+export {
+  Usage,
+  type UsageGetResponse,
+  type UsagePaygoResponse,
+  type UsageGetParams,
+  type UsagePaygoParams,
+} from './usage';
diff --git a/src/resources/billing/usage.ts b/src/resources/billing/usage.ts
@@ -4,6 +4,30 @@ import { APIResource } from '../../resource';
 import * as Core from '../../core';
 
 export class Usage extends APIResource {
+  /**
+   * Returns cost and usage data for a single Cloudflare account, aligned with the
+   * [FinOps FOCUS v1.3](https://focus.finops.org/focus-specification/v1-3/) Cost and
+   * Usage dataset specification.
+   *
+   * Each record represents one billable metric for one account on one day. This
+   * includes all metered usage, including usage that falls within free-tier
+   * allowances and may result in zero cost.
+   *
+   * **Note:** Cost and pricing fields are not yet populated and will be absent from
+   * responses until billing integration is complete.
+   *
+   * When `from` and `to` are omitted, defaults to the start of the current month
+   * through today. The maximum date range is 31 days.
+   */
+  get(params: UsageGetParams, options?: Core.RequestOptions): Core.APIPromise<UsageGetResponse> {
+    const { account_id, ...query } = params;
+    return (
+      this._client.get(`/accounts/${account_id}/billable/usage`, { query, ...options }) as Core.APIPromise<{
+        result: UsageGetResponse;
+      }>
+    )._thenUnwrap((obj) => obj.result);
+  }
+
   /**
    * Returns billable usage data for PayGo (self-serve) accounts. When no query
    * parameters are provided, returns usage for the current billing period. This
@@ -13,14 +37,212 @@ export class Usage extends APIResource {
   paygo(params: UsagePaygoParams, options?: Core.RequestOptions): Core.APIPromise<UsagePaygoResponse> {
     const { account_id, ...query } = params;
     return (
-      this._client.get(`/accounts/${account_id}/billing/usage/paygo`, {
-        query,
-        ...options,
-      }) as Core.APIPromise<{ result: UsagePaygoResponse }>
+      this._client.get(`/accounts/${account_id}/paygo-usage`, { query, ...options }) as Core.APIPromise<{
+        result: UsagePaygoResponse;
+      }>
     )._thenUnwrap((obj) => obj.result);
   }
 }
 
+/**
+ * Contains the array of cost and usage records.
+ */
+export type UsageGetResponse = Array<UsageGetResponse.UsageGetResponseItem>;
+
+export namespace UsageGetResponse {
+  /**
+   * A single cost and usage record for a metered product within a specific charge
+   * period, aligned with the FinOps FOCUS v1.3 specification.
+   */
+  export interface UsageGetResponseItem {
+    /**
+     * Public identifier of the Cloudflare account (account tag).
+     */
+    BillingAccountId: string;
+
+    /**
+     * Display name of the Cloudflare account.
+     */
+    BillingAccountName: string;
+
+    /**
+     * Highest-level classification of a charge based on the nature of how it gets
+     * billed. Currently only "Usage" is supported.
+     */
+    ChargeCategory: 'Usage';
+
+    /**
+     * Self-contained summary of the charge's purpose and price.
+     */
+    ChargeDescription: string;
+
+    /**
+     * Indicates how often a charge occurs. Currently only "Usage-Based" is supported.
+     */
+    ChargeFrequency: 'Usage-Based';
+
+    /**
+     * Exclusive end of the time interval during which the usage was consumed.
+     */
+    ChargePeriodEnd: string;
+
+    /**
+     * Inclusive start of the time interval during which the usage was consumed.
+     */
+    ChargePeriodStart: string;
+
+    /**
+     * Measured usage amount within the charge period. Reflects raw metered consumption
+     * before pricing transformations.
+     */
+    ConsumedQuantity: number;
+
+    /**
+     * Unit of measure for the consumed quantity (e.g., "GB", "Requests",
+     * "vCPU-Hours").
+     */
+    ConsumedUnit: string;
+
+    /**
+     * Name of the entity providing the underlying infrastructure or platform.
+     */
+    HostProviderName: string;
+
+    /**
+     * Name of the entity responsible for invoicing for the services consumed.
+     */
+    InvoiceIssuerName: string;
+
+    /**
+     * Name of the entity that made the services available for purchase.
+     */
+    ServiceProviderName: string;
+
+    /**
+     * The display name of the billable metric. Cloudflare extension; replaces FOCUS
+     * SkuMeter.
+     */
+    x_BillableMetricName: string;
+
+    /**
+     * A charge serving as the basis for invoicing, inclusive of all reduced rates and
+     * discounts while excluding the amortization of upfront charges (one-time or
+     * recurring).
+     */
+    BilledCost?: number | null;
+
+    /**
+     * Currency that a charge was billed in (ISO 4217).
+     */
+    BillingCurrency?: string | null;
+
+    /**
+     * Exclusive end of the billing cycle that contains this usage record.
+     */
+    BillingPeriodEnd?: string | null;
+
+    /**
+     * Inclusive start of the billing cycle that contains this usage record.
+     */
+    BillingPeriodStart?: string | null;
+
+    /**
+     * Indicates whether the row represents a correction to one or more charges
+     * invoiced in a previous billing period.
+     */
+    ChargeClass?: 'Correction' | null;
+
+    /**
+     * Cost calculated by multiplying ContractedUnitPrice and the corresponding
+     * PricingQuantity.
+     */
+    ContractedCost?: number | null;
+
+    /**
+     * The agreed-upon unit price for a single PricingUnit of the associated billable
+     * metric, inclusive of negotiated discounts, if present, while excluding any other
+     * discounts.
+     */
+    ContractedUnitPrice?: number | null;
+
+    /**
+     * The amortized cost of the charge after applying all reduced rates, discounts,
+     * and the applicable portion of relevant, prepaid purchases (one-time or
+     * recurring) that covered the charge.
+     */
+    EffectiveCost?: number | null;
+
+    /**
+     * Cost calculated by multiplying ListUnitPrice and the corresponding
+     * PricingQuantity.
+     */
+    ListCost?: number | null;
+
+    /**
+     * Suggested provider-published unit price for a single PricingUnit of the
+     * associated billable metric, exclusive of any discounts.
+     */
+    ListUnitPrice?: number | null;
+
+    /**
+     * Volume of a given service used or purchased, based on the PricingUnit.
+     */
+    PricingQuantity?: number | null;
+
+    /**
+     * Provider-specified measurement unit for determining unit prices, indicating how
+     * the provider rates measured usage after applying pricing rules like block
+     * pricing.
+     */
+    PricingUnit?: string | null;
+
+    /**
+     * Provider-assigned identifier for an isolated geographic area where a service is
+     * provided.
+     */
+    RegionId?: string | null;
+
+    /**
+     * Name of an isolated geographic area where a service is provided.
+     */
+    RegionName?: string | null;
+
+    /**
+     * Unique identifier assigned to a grouping of services. For Cloudflare, this is
+     * the subscription or contract ID.
+     */
+    SubAccountId?: string;
+
+    /**
+     * Name assigned to a grouping of services. For Cloudflare, this is the
+     * subscription or contract display name.
+     */
+    SubAccountName?: string;
+
+    /**
+     * The unique identifier for the billable metric in the Cloudflare catalog.
+     * Cloudflare extension; replaces FOCUS SkuId.
+     */
+    x_BillableMetricId?: string;
+
+    /**
+     * The product family the charge belongs to (e.g., "R2", "Workers"). Cloudflare
+     * extension; replaces FOCUS ServiceName.
+     */
+    x_ProductFamilyName?: string;
+
+    /**
+     * The identifier for the Cloudflare zone (zone tag). Cloudflare extension.
+     */
+    x_ZoneId?: string | null;
+
+    /**
+     * The display name of the Cloudflare zone. Cloudflare extension.
+     */
+    x_ZoneName?: string | null;
+  }
+}
+
 /**
  * Contains the array of billable usage records.
  */
@@ -87,26 +309,65 @@ export namespace UsagePaygoResponse {
      * Identifies the Cloudflare service.
      */
     ServiceName: string;
+
+    /**
+     * Identifies the product family for the Cloudflare service.
+     */
+    ServiceFamilyName?: string;
   }
 }
 
+export interface UsageGetParams {
+  /**
+   * Path param: Represents a Cloudflare resource identifier tag.
+   */
+  account_id: string;
+
+  /**
+   * Query param: Start date for the usage query (ISO 8601). Required if `to` is set.
+   * When omitted along with `to`, defaults to the start of the current month.
+   * Filters by charge period (when consumption happened), not billing period. The
+   * maximum date range is 31 days.
+   */
+  from?: string;
+
+  /**
+   * Query param: Filter results by billable metric id (e.g.,
+   * workers_standard_requests).
+   */
+  metric?: string;
+
+  /**
+   * Query param: End date for the usage query (ISO 8601). Required if `from` is set.
+   * When omitted along with `from`, defaults to today. Filters by charge period
+   * (when consumption happened), not billing period. The maximum date range is 31
+   * days.
+   */
+  to?: string;
+}
+
 export interface UsagePaygoParams {
   /**
    * Path param: Represents a Cloudflare resource identifier tag.
    */
   account_id: string;
 
   /**
-   * Query param: Defines the start date for the usage query (e.g., 2025-02-01).
+   * Query param: Start date for the usage query (ISO 8601).
    */
   from?: string;
 
   /**
-   * Query param: Defines the end date for the usage query (e.g., 2025-03-01).
+   * Query param: End date for the usage query (ISO 8601).
    */
   to?: string;
 }
 
 export declare namespace Usage {
-  export { type UsagePaygoResponse as UsagePaygoResponse, type UsagePaygoParams as UsagePaygoParams };
+  export {
+    type UsageGetResponse as UsageGetResponse,
+    type UsagePaygoResponse as UsagePaygoResponse,
+    type UsageGetParams as UsageGetParams,
+    type UsagePaygoParams as UsagePaygoParams,
+  };
 }
diff --git a/tests/api-resources/billing/usage.test.ts b/tests/api-resources/billing/usage.test.ts
@@ -10,6 +10,26 @@ const client = new Cloudflare({
 });
 
 describe('resource usage', () => {
+  test('get: only required params', async () => {
+    const responsePromise = client.billing.usage.get({ account_id: '023e105f4ecef8ad9ca31a8372d0c353' });
+    const rawResponse = await responsePromise.asResponse();
+    expect(rawResponse).toBeInstanceOf(Response);
+    const response = await responsePromise;
+    expect(response).not.toBeInstanceOf(Response);
+    const dataAndResponse = await responsePromise.withResponse();
+    expect(dataAndResponse.data).toBe(response);
+    expect(dataAndResponse.response).toBe(rawResponse);
+  });
+
+  test('get: required and optional params', async () => {
+    const response = await client.billing.usage.get({
+      account_id: '023e105f4ecef8ad9ca31a8372d0c353',
+      from: '2025-05-01',
+      metric: 'workers_standard_requests',
+      to: '2025-05-31',
+    });
+  });
+
   test('paygo: only required params', async () => {
     const responsePromise = client.billing.usage.paygo({ account_id: '023e105f4ecef8ad9ca31a8372d0c353' });
     const rawResponse = await responsePromise.asResponse();
@@ -24,8 +44,8 @@ describe('resource usage', () => {
   test('paygo: required and optional params', async () => {
     const response = await client.billing.usage.paygo({
       account_id: '023e105f4ecef8ad9ca31a8372d0c353',
-      from: '2025-02-01',
-      to: '2025-03-01',
+      from: '2025-05-01',
+      to: '2025-05-31',
     });
   });
 });
