Class: MetronomeSDK::Resources::V1::Customers::Invoices

Inherits:
Object
  • Object
show all
Defined in:
lib/metronome_sdk/resources/v1/customers/invoices.rb

Instance Method Summary collapse

Constructor Details

#initialize(client:) ⇒ Invoices

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a new instance of Invoices.

Parameters:



361
362
363
 
# File 'lib/metronome_sdk/resources/v1/customers/invoices.rb', line 361

def initialize(client:)
  @client = client
end

Instance Method Details

#add_charge(customer_id: , charge_id: , customer_plan_id: , description: , invoice_start_timestamp: , price: , quantity: , request_options: {}) ⇒ MetronomeSDK::Models::V1::Customers::InvoiceAddChargeResponse

Some parameter documentations has been truncated, see Models::V1::Customers::InvoiceAddChargeParams for more details.

Add a one time charge to the specified invoice. This is a Plans (deprecated) endpoint. New clients should implement using Contracts.

Parameters:

  • customer_id (String) —

    Path param:

  • charge_id (String) —

    Body param: The Metronome ID of the charge to add to the invoice. Note that the

  • customer_plan_id (String) —

    Body param: The Metronome ID of the customer plan to add the charge to.

  • description (String) —

    Body param:

  • invoice_start_timestamp (Time) —

    Body param: The start_timestamp of the invoice to add the charge to.

  • price (Float) —

    Body param: The price of the charge. This price will match the currency on the i

  • quantity (Float) —

    Body param:

  • request_options (MetronomeSDK::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



202
203
204
205
206
207
208
209
210
211
212
213
214
215
 
# File 'lib/metronome_sdk/resources/v1/customers/invoices.rb', line 202

def add_charge(params)
  parsed, options = MetronomeSDK::V1::Customers::InvoiceAddChargeParams.dump_request(params)
  customer_id =
    parsed.delete(:customer_id) do
      raise ArgumentError.new("missing required path argument #{_1}")
    end
  @client.request(
    method: :post,
    path: ["v1/customers/%1$s/addCharge", customer_id],
    body: parsed,
    model: MetronomeSDK::Models::V1::Customers::InvoiceAddChargeResponse,
    options: options
  )
end

#list(customer_id: , credit_type_id: nil, ending_before: nil, limit: nil, next_page: nil, skip_zero_qty_line_items: nil, sort: nil, starting_on: nil, status: nil, request_options: {}) ⇒ MetronomeSDK::Internal::CursorPage<MetronomeSDK::Models::V1::Customers::Invoice>

Some parameter documentations has been truncated, see Models::V1::Customers::InvoiceListParams for more details.

Retrieves a paginated list of invoices for a specific customer, with flexible filtering options to narrow results by status, date range, credit type, and more. This endpoint provides a comprehensive view of a customer’s billing history and current charges, supporting both real-time billing dashboards and historical reporting needs.

### Use this endpoint to:

  • Display historical invoice details in customer-facing dashboards or billing portals.

  • Retrieve current month draft invoices to show customers their month-to-date spend.

  • Access finalized invoices for historical billing records and payment reconciliation.

  • Validate customer pricing and credit applications for customer support queries.

  • Generate financial reports by filtering invoices within specific date ranges

### Key response fields:

Array of invoice objects containing:

  • Invoice ID and status (DRAFT, FINALIZED, VOID)

  • Invoice type (USAGE, SCHEDULED)

  • Billing period start and end dates

  • Issue date and due date

  • Total amount, subtotal, and amount due

  • Applied credits summary

  • Contract ID reference

  • External billing provider status (if integrated with Stripe, etc.)

  • Pagination metadata ‘next_page` cursor

### Usage guidelines:

  • The endpoint returns invoice summaries; use the Get Invoice endpoint for detailed line items

  • Draft invoices are continuously updated as new usage is reported and will show real-time spend

  • Results are ordered by creation date descending by default (newest first)

  • When filtering by date range, the filter applies to the billing period, not the issue date

  • For customers with many invoices, implement pagination to ensure all results are retrieved External billing provider statuses (like Stripe payment status) are included when applicable

  • Voided invoices are included in results by default unless filtered out by status

Parameters:

  • customer_id (String) —

    Path param:

  • credit_type_id (String) —

    Query param: Only return invoices for the specified credit type

  • ending_before (Time) —

    Query param: RFC 3339 timestamp (exclusive). Invoices will only be returned for

  • limit (Integer) —

    Query param: Max number of results that should be returned

  • next_page (String) —

    Query param: Cursor that indicates where the next page of results should start.

  • skip_zero_qty_line_items (Boolean) —

    Query param: If set, all zero quantity line items will be filtered out of the re

  • sort (Symbol, MetronomeSDK::Models::V1::Customers::InvoiceListParams::Sort) —

    Query param: Invoice sort order by issued_at, e.g. date_asc or date_desc. Defau

  • starting_on (Time) —

    Query param: RFC 3339 timestamp (inclusive). Invoices will only be returned for

  • status (String) —

    Query param: Invoice status, e.g. DRAFT, FINALIZED, or VOID

  • request_options (MetronomeSDK::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
 
# File 'lib/metronome_sdk/resources/v1/customers/invoices.rb', line 159

def list(params)
  parsed, options = MetronomeSDK::V1::Customers::InvoiceListParams.dump_request(params)
  customer_id =
    parsed.delete(:customer_id) do
      raise ArgumentError.new("missing required path argument #{_1}")
    end
  @client.request(
    method: :get,
    path: ["v1/customers/%1$s/invoices", customer_id],
    query: parsed,
    page: MetronomeSDK::Internal::CursorPage,
    model: MetronomeSDK::V1::Customers::Invoice,
    options: options
  )
end

#list_breakdowns(customer_id: , ending_before: , starting_on: , credit_type_id: nil, limit: nil, next_page: nil, skip_zero_qty_line_items: nil, sort: nil, status: nil, window_size: nil, request_options: {}) ⇒ MetronomeSDK::Internal::CursorPage<MetronomeSDK::Models::V1::Customers::InvoiceListBreakdownsResponse>

Some parameter documentations has been truncated, see Models::V1::Customers::InvoiceListBreakdownsParams for more details.

Retrieve granular time-series breakdowns of invoice data at hourly or daily intervals. This endpoint transforms standard invoices into detailed timelines, enabling you to track usage patterns, identify consumption spikes, and provide customers with transparency into their billing details throughout the billing period.

### Use this endpoint to:

  • Build usage analytics dashboards showing daily or hourly consumption trends

  • Identify peak usage periods for capacity planning and cost optimization

  • Generate detailed billing reports for finance teams and customer success

  • Troubleshoot billing disputes by examining usage patterns at specific times

  • Power real-time cost monitoring and alerting systems

### Key response fields:

An array of BreakdownInvoice objects, each containing:

  • All standard invoice fields (ID, customer, commit, line items, totals, status)

  • Line items with quantities and costs for that specific period

  • ‘breakdown_start_timestamp`: Start of the specific time window

  • ‘breakdown_end_timestamp`: End of the specific time window

  • ‘next_page`: Pagination cursor for large result sets

### Usage guidelines:

  • Time granularity: Set ‘window_size` to hour or day based on your analysis needs

  • Response limits: Daily breakdowns return up to 35 days; hourly breakdowns return up to 24 hours per request

  • Date filtering: Use ‘starting_on` and `ending_before` to focus on specific periods

  • Performance: For large date ranges, use pagination to retrieve all data efficiently

  • Backdated usage: If usage events arrive after invoice finalization, breakdowns will reflect the updated usage

  • Zero quantity filtering: Use ‘skip_zero_qty_line_items=true` to exclude periods with no usage

Parameters:

  • customer_id (String) —

    Path param:

  • ending_before (Time) —

    Query param: RFC 3339 timestamp. Breakdowns will only be returned for time windo

  • starting_on (Time) —

    Query param: RFC 3339 timestamp. Breakdowns will only be returned for time windo

  • credit_type_id (String) —

    Query param: Only return invoices for the specified credit type

  • limit (Integer) —

    Query param: Max number of results that should be returned. For daily breakdowns

  • next_page (String) —

    Query param: Cursor that indicates where the next page of results should start.

  • skip_zero_qty_line_items (Boolean) —

    Query param: If set, all zero quantity line items will be filtered out of the re

  • sort (Symbol, MetronomeSDK::Models::V1::Customers::InvoiceListBreakdownsParams::Sort) —

    Query param: Invoice sort order by issued_at, e.g. date_asc or date_desc. Defau

  • status (String) —

    Query param: Invoice status, e.g. DRAFT or FINALIZED

  • window_size (Symbol, MetronomeSDK::Models::V1::Customers::InvoiceListBreakdownsParams::WindowSize) —

    Query param: The granularity of the breakdowns to return. Defaults to day.

  • request_options (MetronomeSDK::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
 
# File 'lib/metronome_sdk/resources/v1/customers/invoices.rb', line 287

def list_breakdowns(params)
  parsed, options = MetronomeSDK::V1::Customers::InvoiceListBreakdownsParams.dump_request(params)
  customer_id =
    parsed.delete(:customer_id) do
      raise ArgumentError.new("missing required path argument #{_1}")
    end
  @client.request(
    method: :get,
    path: ["v1/customers/%1$s/invoices/breakdowns", customer_id],
    query: parsed,
    page: MetronomeSDK::Internal::CursorPage,
    model: MetronomeSDK::Models::V1::Customers::InvoiceListBreakdownsResponse,
    options: options
  )
end

#retrieve(customer_id: , invoice_id: , skip_zero_qty_line_items: nil, request_options: {}) ⇒ MetronomeSDK::Models::V1::Customers::InvoiceRetrieveResponse

Some parameter documentations has been truncated, see Models::V1::Customers::InvoiceRetrieveParams for more details.

Retrieve detailed information for a specific invoice by its unique identifier. This endpoint returns comprehensive invoice data including line items, applied credits, totals, and billing period details for both finalized and draft invoices.

### Use this endpoint to:

  • Display historical invoice details in customer-facing dashboards or billing portals.

  • Retrieve current month draft invoices to show customers their month-to-date spend.

  • Access finalized invoices for historical billing records and payment reconciliation.

  • Validate customer pricing and credit applications for customer support queries.

### Key response fields:

Invoice status (DRAFT, FINALIZED, VOID) Billing period start and end dates Total amount and amount due after credits Detailed line items broken down by:

  • Customer and contract information

  • Invoice line item type

  • Product/service name and ID

  • Quantity consumed

  • Unit and total price

  • Time period for usage-based charges

  • Applied credits or prepaid commitments

### Usage guidelines:

  • Draft invoices update in real-time as usage is reported and may change before finalization

  • The response includes both usage-based line items (e.g., API calls, data processed) and scheduled charges (e.g., monthly subscriptions, commitment fees)

  • Credit and commitment applications are shown as separate line items with negative amounts

  • For voided invoices, the response will indicate VOID status but retain all original line item details

Parameters:

  • customer_id (String) —

    Path param:

  • invoice_id (String) —

    Path param:

  • skip_zero_qty_line_items (Boolean) —

    Query param: If set, all zero quantity line items will be filtered out of the re

  • request_options (MetronomeSDK::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
 
# File 'lib/metronome_sdk/resources/v1/customers/invoices.rb', line 65

def retrieve(params)
  parsed, options = MetronomeSDK::V1::Customers::InvoiceRetrieveParams.dump_request(params)
  customer_id =
    parsed.delete(:customer_id) do
      raise ArgumentError.new("missing required path argument #{_1}")
    end
  invoice_id =
    parsed.delete(:invoice_id) do
      raise ArgumentError.new("missing required path argument #{_1}")
    end
  @client.request(
    method: :get,
    path: ["v1/customers/%1$s/invoices/%2$s", customer_id, invoice_id],
    query: parsed,
    model: MetronomeSDK::Models::V1::Customers::InvoiceRetrieveResponse,
    options: options
  )
end

#retrieve_pdf(customer_id: , invoice_id: , request_options: {}) ⇒ StringIO

Retrieve a PDF version of a specific invoice by its unique identifier. This endpoint generates a professionally formatted invoice document suitable for sharing with customers, accounting teams, or for record-keeping purposes.

### Use this endpoint to:

  • Provide customers with downloadable or emailable copies of their invoices

  • Support accounting and finance teams with official billing documents

  • Maintain accurate records of billing transactions for audits and compliance

### Key response details:

  • The response is a binary PDF file representing the full invoice

  • The PDF includes all standard invoice information such as line items, totals, billing period, and customer details

  • The document is formatted for clarity and professionalism, suitable for official use

### Usage guidelines:

  • Ensure the ‘invoice_id` corresponds to an existing invoice for the specified `customer_id`

  • The PDF is generated on-demand; frequent requests for the same invoice may impact performance

  • Use appropriate headers to handle the binary response in your application (e.g., setting ‘Content-Type: application/pdf`)

Parameters:

Returns:

  • (StringIO)

See Also:



339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
 
# File 'lib/metronome_sdk/resources/v1/customers/invoices.rb', line 339

def retrieve_pdf(params)
  parsed, options = MetronomeSDK::V1::Customers::InvoiceRetrievePdfParams.dump_request(params)
  customer_id =
    parsed.delete(:customer_id) do
      raise ArgumentError.new("missing required path argument #{_1}")
    end
  invoice_id =
    parsed.delete(:invoice_id) do
      raise ArgumentError.new("missing required path argument #{_1}")
    end
  @client.request(
    method: :get,
    path: ["v1/customers/%1$s/invoices/%2$s/pdf", customer_id, invoice_id],
    headers: {"accept" => "application/pdf"},
    model: StringIO,
    options: options
  )
end