Stay organized with collectionsSave and categorize content based on your preferences.
Monthly invoices for a Google Ads account can be retrieved using theInvoiceService.
Prerequisites
Havemonthly invoicingenabled for the Google Ads account. See the guides on accountbilling
setupsandbudgetsto learn how to manage billing
using the Google Ads API.
If set,login-customer-idmust
specify the customer ID of a manager account that is managing the Google Ads
account for which you're retrieving invoices. This is labeled as thepaying managerin the
Google Ads UI.
If you have a consolidated billing setup, the Google Ads API returns invoices for all
customers under the same billing setup, not just the invoice for thecustomer_idspecified in the API request.
Thecustomer_idmust be a Google Ads serving account. To get all the
invoices for a paying manager, make one request per Google Ads serving
account.
# Issues a request to list invoices.response=client.get_service("InvoiceService").list_invoices(customer_id=customer_id,billing_setup=client.get_service("GoogleAdsService").billing_setup_path(customer_id,billing_setup_id),# The year needs to be 2019 or later, per the docs:# https://developers.google.com/google-ads/api/docs/billing/invoice?hl=en#retrieving_invoicesissue_year=str(last_month.year),issue_month=last_month.strftime("%B").upper(),)
# Issues a request to list invoices.response=client.service.invoice.list_invoices(customer_id:customer_id,billing_setup:client.path.billing_setup(customer_id,billing_setup_id),# The year needs to be 2019 or later.issue_year:last_month.year.to_s,# '%^B' option returns the uppercased full month name (e.g. 'JANUARY').issue_month:last_month.strftime("%^B").to_sym,)
# Issue the request.my$response=$api_client->InvoiceService()->list({customerId=>$customer_id,billingSetup=>Google::Ads::GoogleAds::V21::Utils::ResourceNames::billing_setup(($customer_id,$billing_setup_id)),# The year needs to be 2019 or later.issueYear=>strftime("%Y",@last_month),issueMonth=>uc(strftime("%B",@last_month))});
AnInvoiceprovides information about relatedaccountsas a list ofAccountSummaryobjects
in theaccount_summariesfield. It includes details about billing corrections,
adjustments, export charges, and regulatory costs.
Understand amounts
All the amounts provided inAccountBudgetSummary,AccountSummaryandInvoiceobjects are attributable during their service
periods and are evaluated according to these rules:
forinvoiceinresponse.invoices:print(f"""- Found the invoice{invoice.resource_name}ID (also known as Invoice Number): '{invoice.id}'Type:{invoice.type_}Billing setup ID: '{invoice.billing_setup}'Payments account ID (also known as Billing Account Number): '{invoice.payments_account_id}'Payments profile ID (also known as Billing ID): '{invoice.payments_profile_id}'Issue date (also known as Invoice Date):{invoice.issue_date}Due date:{invoice.due_date}Currency code:{invoice.currency_code}Service date range (inclusive): from{invoice.service_date_range.start_date}to{invoice.service_date_range.end_date}Adjustments:subtotal{_micros_to_currency(invoice.adjustments_subtotal_amount_micros)}tax{_micros_to_currency(invoice.adjustments_tax_amount_micros)}total{_micros_to_currency(invoice.adjustments_total_amount_micros)}Regulatory costs:subtotal{_micros_to_currency(invoice.regulatory_costs_subtotal_amount_micros)}tax{_micros_to_currency(invoice.regulatory_costs_tax_amount_micros)}total{_micros_to_currency(invoice.regulatory_costs_total_amount_micros)}Replaced invoices:{invoice.replaced_invoices.join(", ")ifinvoice.replaced_invoiceselse"none"}Amounts:subtotal{_micros_to_currency(invoice.subtotal_amount_micros)}tax{_micros_to_currency(invoice.tax_amount_micros)}total{_micros_to_currency(invoice.total_amount_micros)}Corrected invoice:{invoice.corrected_invoiceor"none"}PDF URL:{invoice.pdf_url}Account budgets:""")foraccount_budget_summaryininvoice.account_budget_summaries:print(f"""- Account budget '{account_budget_summary.account_budget}':Name (also known as Account Budget): '{account_budget_summary.account_budget_name}'Customer (also known as Account ID): '{account_budget_summary.customer}'Customer descriptive name (also known as Account): '{account_budget_summary.customer_descriptive_name}'Purchase order number (also known as Purchase Order): '{account_budget_summary.purchase_order_number}'Billing activity date range (inclusive):from #{account_budget_summary.billable_activity_date_range.start_date}to #{account_budget_summary.billable_activity_date_range.end_date}Amounts:subtotal '{_micros_to_currency(account_budget_summary.subtotal_amount_micros)}'tax '{_micros_to_currency(account_budget_summary.tax_amount_micros)}'total '{_micros_to_currency(account_budget_summary.total_amount_micros)}'""")
# Iterates over all invoices retrieved and prints their information.response.invoices.eachdo|invoice|puts<<~OUTPUT-Foundtheinvoice'#{invoice.resource_name}'ID(alsoknownasInvoiceNumber):'#{invoice.id}'Type:#{invoice.type}BillingSetupID:'#{invoice.billing_setup}'PaymentsaccountID(alsoknownasBillingAccountNumber):'#{invoice.payments_account_id}'PaymentsprofileID(alsoknownasBillingID):'#{invoice.payments_profile_id}'Issuedate(alsoknownasInvoiceDate):#{invoice.issue_date}Duedate:#{invoice.due_date}Currencycode:#{invoice.currency_code}Servicedaterange(inclusive):from#{invoice.service_date_range.start_date}to#{invoice.service_date_range.end_date}Adjustments:subtotal'#{micro_to_base(invoice.adjustments_subtotal_amount_micros)}'tax'#{micro_to_base(invoice.adjustments_tax_amount_micros)}'total'#{micro_to_base(invoice.adjustments_total_amount_micros)}'Regulatorycosts:subtotal'#{micro_to_base(invoice.regulatory_costs_subtotal_amount_micros)}'tax'#{micro_to_base(invoice.regulatory_costs_tax_amount_micros)}'total'#{micro_to_base(invoice.regulatory_costs_total_amount_micros)}'Replacedinvoices:'#{invoice.replaced_invoices?invoice.replaced_invoices.join(", "):'none'}'Amounts:subtotal'#{micro_to_base(invoice.subtotal_amount_micros)}'tax'#{micro_to_base(invoice.tax_amount_micros)}'total'#{micro_to_base(invoice.total_amount_micros)}'Correctedinvoice:'#{invoice.corrected_invoices?invoice.corrected_invoices:'none'}'PDFURL:'#{invoice.pdf_url}'Accountbudgets:OUTPUTinvoice.account_budget_summaries.eachdo|account_budget_summary|puts<<~OUTPUT\tAccountbudget'#{account_budget_summary.account_budget}':\tName(alsoknownasAccountBudget):'#{account_budget_summary.account_budget_name}'\tCustomer(alsoknownasAccountID):'#{account_budget_summary.customer}'\tCustomerdescriptivename(alsoknownasAccount):'#{account_budget_summary.customer_descriptive_name}'\tPurchaseordernumber(alsoknownasPurchaseOrder):'#{account_budget_summary.purchase_order_number}'\tBillingactivitydaterange(inclusive):\tfrom#{account_budget_summary.billable_activity_date_range.start_date}\tto#{account_budget_summary.billable_activity_date_range.end_date}\tAmounts:\tsubtotal'#{micro_to_base(account_budget_summary.subtotal_amount_micros)}'\ttax'#{micro_to_base(account_budget_summary.tax_amount_micros)}'\ttotal'#{micro_to_base(account_budget_summary.total_amount_micros)}'OUTPUTendend
# Iterate over all invoices retrieved and print their information.foreachmy$invoice(@$response){printf"- Found the invoice '%s':\n"." ID (also known as Invoice Number): '%s'\n"." Type: %s\n"." Billing setup ID: '%s'\n"." Payments account ID (also known as Billing Account Number): '%s'\n"." Payments profile ID (also known as Billing ID): '%s'\n"." Issue date (also known as Invoice Date): %s\n"." Due date: %s\n"." Currency code: %s\n"." Service date range (inclusive): from %s to %s\n"." Adjustments: subtotal '%.2f', tax '%.2f', total '%.2f'\n"." Regulatory costs: subtotal '%.2f', tax '%.2f', total '%.2f'\n"." Replaced invoices: '%s'\n"." Amounts: subtotal '%.2f', tax '%.2f', total '%.2f'\n"." Corrected invoice: '%s'\n"." PDF URL: '%s'\n"." Account budgets:\n",$invoice->{resourceName},$invoice->{id},$invoice->{type},$invoice->{billingSetup},$invoice->{paymentsAccountId},$invoice->{paymentsProfileId},$invoice->{issueDate},$invoice->{dueDate},$invoice->{currencyCode},$invoice->{serviceDateRange}{startDate},$invoice->{serviceDateRange}{endDate},micro_to_base($invoice->{adjustmentsSubtotalAmountMicros}),micro_to_base($invoice->{adjustmentsTaxAmountMicros}),micro_to_base($invoice->{adjustmentsTotalAmountMicros}),micro_to_base($invoice->{regulatoryCostsSubtotalAmountMicros}),micro_to_base($invoice->{regulatoryCostsTaxAmountMicros}),micro_to_base($invoice->{regulatoryCostsTotalAmountMicros}),$invoice->{replacedInvoices}?join(',',@{$invoice->{replacedInvoices}}):"none",micro_to_base($invoice->{subtotalAmountMicros}),micro_to_base($invoice->{taxAmountMicros}),micro_to_base($invoice->{totalAmountMicros}),$invoice->{correctedInvoice}?$invoice->{correctedInvoice}:"none",$invoice->{pdfUrl};foreachmy$account_budget_summary(@{$invoice->{accountBudgetSummaries}}){printf" - Account budget '%s':\n"." Name (also known as Account Budget): '%s'\n"." Customer (also known as Account ID): '%s'\n"." Customer descriptive name (also known as Account): '%s'\n"." Purchase order number (also known as Purchase Order): '%s'\n"." Billing activity date range (inclusive): from %s to %s\n"." Amounts: subtotal '%.2f', tax '%.2f', total '%.2f'\n",$account_budget_summary->{accountBudget},$account_budget_summary->{accountBudgetName}?$account_budget_summary->{accountBudgetName}:"none",$account_budget_summary->{customer},$account_budget_summary->{customerDescriptiveName}?$account_budget_summary->{customerDescriptiveName}:"none",$account_budget_summary->{purchaseOrderNumber}?$account_budget_summary->{purchaseOrderNumber}:"none",$account_budget_summary->{billableActivityDateRange}{startDate},$account_budget_summary->{billableActivityDateRange}{endDate},$account_budget_summary->{subtotalAmountMicros},$account_budget_summary->{taxAmountMicros},$account_budget_summary->{totalAmountMicros};}}
Any invoice can be downloaded as a PDF file. Once you haveretrievedtheInvoice, you
need to send an HTTP request for the URL that is stored in itspdf_urlfield. This request must be
authenticated using the same Google Account used to retrieve the invoice; that
is, you need to specify an OAuth access token generated using the Google Account
in theAuthorization: Bearerrequest header:
curl --request GET \
--header "Authorization: Beareraccess token" \Invoice.pdf_url>filename.pdf
The result is an invoice PDF content stored in the filefilename.pdf.
Common error codes
Scenario
Error Code
Missing or empty billing setup, issue year, or issue month.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Missing the information I need","missingTheInformationINeed","thumb-down"],["Too complicated / too many steps","tooComplicatedTooManySteps","thumb-down"],["Out of date","outOfDate","thumb-down"],["Samples / code issue","samplesCodeIssue","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-09-03 UTC."],[[["\u003cp\u003eGoogle Ads monthly invoices can be retrieved programmatically using the \u003ccode\u003eInvoiceService\u003c/code\u003e within the Google Ads API.\u003c/p\u003e\n"],["\u003cp\u003eInvoices contain detailed information like IDs, dates, amounts, PDF URLs, adjustments, and account budget summaries.\u003c/p\u003e\n"],["\u003cp\u003eCode examples are provided in Java, C#, PHP, Python, Ruby, and Perl to demonstrate invoice retrieval and data extraction.\u003c/p\u003e\n"],["\u003cp\u003eInvoices issued before January 1, 2019, are not retrievable through this method.\u003c/p\u003e\n"],["\u003cp\u003eDiscrepancies between invoice amounts and serving metrics or account budgets are expected due to potential late adjustments.\u003c/p\u003e\n"]]],[],null,[]]
