From 02282ab264c182697d60111e21a633fe4aceb004 Mon Sep 17 00:00:00 2001
From: Kyle <tungleduy.xyz@gmail.com>
Date: Thu, 12 Nov 2026 00:25:07 +0700
Subject: [PATCH] Add include_invoice_components option to
 Account.paginated_invoices

Paginated account invoices are shallow, so amount and balance are 0.
Optionally send includeInvoiceComponents=true so the server loads the
components of the invoices of the requested page.

The new argument is last, so existing callers are unaffected.

See killbill/killbill-admin-ui#678 and killbill/killbill#2334

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
---
 lib/killbill_client/models/account.rb | 16 +++++++-----
 spec/killbill_client/account_spec.rb  | 37 +++++++++++++++++++++++++++
 2 files changed, 47 insertions(+), 6 deletions(-)
 create mode 100644 spec/killbill_client/account_spec.rb

diff --git a/lib/killbill_client/models/account.rb b/lib/killbill_client/models/account.rb
index 2bd9499..95107f4 100644
--- a/lib/killbill_client/models/account.rb
+++ b/lib/killbill_client/models/account.rb
@@ -84,13 +84,17 @@ def paginated_bundles(account_id, offset = 0, limit = 100, audit = "NONE", optio
                           Bundle
         end
 
-        def paginated_invoices(account_id, offset = 0, limit = 100, audit = "NONE", options = {})
+        # By default, invoices in a page are shallow (no items), i.e. amount, balance, etc. are 0.
+        # Set include_invoice_components to load the components of the invoices of the requested page only.
+        def paginated_invoices(account_id, offset = 0, limit = 100, audit = "NONE", options = {}, include_invoice_components = false)
+          params = {
+            :offset => offset,
+            :limit => limit,
+            :audit => audit
+          }
+          params[:includeInvoiceComponents] = true if include_invoice_components
           get "#{KILLBILL_API_ACCOUNTS_PREFIX}/#{account_id}/invoices/pagination",
-                   {
-                    :offset => offset,
-                    :limit => limit,
-                    :audit => audit
-                   },
+                   params,
                    options,
                    Invoice
         end
diff --git a/spec/killbill_client/account_spec.rb b/spec/killbill_client/account_spec.rb
new file mode 100644
index 0000000..db8e596
--- /dev/null
+++ b/spec/killbill_client/account_spec.rb
@@ -0,0 +1,37 @@
+require 'spec_helper'
+
+describe KillBillClient::Model::Account do
+
+  def json_response(body)
+    response = Net::HTTPOK.new('1.1', '200', 'OK')
+    response['Content-Type'] = 'application/json'
+    response.instance_variable_set(:@read, true)
+    response.instance_variable_set(:@body, body)
+    response
+  end
+
+  describe '.paginated_invoices' do
+    let(:account_id) { 'e6f0d4ab-0d2b-4a8f-9a5c-0a8f5b1c2d3e' }
+    let(:uri) { "/1.0/kb/accounts/#{account_id}/invoices/pagination" }
+
+    it 'does not request invoice components by default' do
+      expect(KillBillClient::API).to receive(:get)
+                                       .with(uri, {:offset => 0, :limit => 100, :audit => 'NONE'}, {:api_key => 'key'})
+                                       .and_return(json_response('[]'))
+
+      described_class.paginated_invoices(account_id, 0, 100, 'NONE', {:api_key => 'key'})
+    end
+
+    it 'requests invoice components when asked to' do
+      expect(KillBillClient::API).to receive(:get)
+                                       .with(uri, {:offset => 10, :limit => 50, :audit => 'NONE', :includeInvoiceComponents => true}, {:api_key => 'key'})
+                                       .and_return(json_response('[{"invoiceId":"abc","amount":12.5,"balance":2.5}]'))
+
+      invoices = described_class.paginated_invoices(account_id, 10, 50, 'NONE', {:api_key => 'key'}, true)
+
+      expect(invoices.size).to eq(1)
+      expect(invoices.first.amount).to eq(12.5)
+      expect(invoices.first.balance).to eq(2.5)
+    end
+  end
+end