InvoiceStay organized with collectionsSave and categorize content based on your preferences.
AI-generated Key Takeaways
Monthly invoices for a Google Ads account can be retrieved using theInvoiceService.
Retrieving invoices requires monthly invoicing to be enabled and potentially alogin-customer-idspecifying a paying manager.
You must use theInvoiceService.ListInvoicesmethod withcustomer_id,billing_setup,issue_year, andissue_monthparameters to retrieve invoices.
Invoices issued before January 1, 2019, cannot be requested.
An invoice PDF can be downloaded by sending an authenticated HTTP GET request to thepdf_urlof the retrieved Invoice object.
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::V22::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-11-05 UTC."],[],[]]
