> ## Documentation Index
> Fetch the complete documentation index at: https://docs.base44.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Get Google Ads workspace debt
> This API is in beta. Endpoints, fields, and behavior may still change, so avoid depending on it in production.
Returns what the workspace owes for Google Ads spend, and whether it can be settled.
The balance is workspace-wide rather than per app. Base44 holds Google Ads at the workspace level, so this resolves the held account across every app in the workspace and reports it from whichever app you ask through. That is why `app_id` in the response can name a different app from the one in the path. Read `state` first, since `no_workspace_debt` is the normal answer and leaves every other field at a neutral default rather than omitting it.
Nothing here charges anything. Settling a balance is a card transaction Base44 deliberately keeps out of this API, so treat a `payable` state as something to raise with whoever owns the card.
Unlike the rest of the Google Ads API, this endpoint stays available while Google Ads is switched off for you, so a workspace can always see what it owes.
This endpoint accepts a personal API key. Workspace API keys are not authorized for it and are rejected with a 403.
The response includes fields beyond the ones documented here. Don't rely on undocumented response fields, as they can change at any time.
## OpenAPI
````yaml /developers/references/app-management/app-management-openapi.json get /api/apps/{app_id}/google-ads/billing/workspace-debt
openapi: 3.1.0
info:
title: Base44 App Management API
version: 1.0.0
servers:
- url: https://app.base44.com
security:
- ApiKeyAuth: []
paths:
/api/apps/{app_id}/google-ads/billing/workspace-debt:
get:
summary: Get Google Ads workspace debt
description: >-
This API is in beta. Endpoints, fields, and behavior may still
change, so avoid depending on it in production.
Returns what the workspace owes for Google Ads spend, and whether it can
be settled.
The balance is workspace-wide rather than per app. Base44 holds Google
Ads at the workspace level, so this resolves the held account across
every app in the workspace and reports it from whichever app you ask
through. That is why `app_id` in the response can name a different app
from the one in the path. Read `state` first, since `no_workspace_debt`
is the normal answer and leaves every other field at a neutral default
rather than omitting it.
Nothing here charges anything. Settling a balance is a card transaction
Base44 deliberately keeps out of this API, so treat a `payable` state as
something to raise with whoever owns the card.
Unlike the rest of the Google Ads API, this endpoint stays
available while Google Ads is switched off for you, so a workspace can
always see what it owes.
This endpoint accepts a personal API key. Workspace API keys are
not authorized for it and are rejected with a 403.
The response includes fields beyond the ones documented here.
Don't rely on undocumented response fields, as they can change at any
time.
operationId: >-
get_workspace_debt_recovery_summary_api_apps__app_id__google_ads_billing_workspace_debt_get
parameters:
- name: app_id
in: path
required: true
schema:
type: string
description: ID of the app whose Google Ads campaigns to manage.
title: App Id
description: ID of the app whose Google Ads campaigns to manage.
example: 6820f3a4e7b91d003c45a1f2
responses:
'200':
description: What the workspace owes, and whether it can be settled.
content:
application/json:
schema:
$ref: '#/components/schemas/WorkspaceDebtSummary'
'401':
description: Missing or invalid credentials.
'403':
description: >-
You don't have access to this app, the app does not exist, or you
used a workspace API key. A missing app and an app you cannot reach
are deliberately the same answer.
components:
schemas:
WorkspaceDebtSummary:
properties:
state:
type: string
title: State
description: >-
What can be done about the balance. `no_workspace_debt` means
nothing is held. `payable` means there is an invoice and a usable
card. `requires_payment_method` and `requires_payment_refresh` both
mean a card is needed. `pending_payment` means a charge is already
in flight. `paid_recovery_incomplete` means the invoice is paid but
the account is still held. `unavailable` means the balance cannot be
settled right now, including when `stripe_unavailable` is `true`.
`no_debt` and `not_recoverable` mean the account has no settleable
balance.
example: payable
account_id:
anyOf:
- type: string
- type: 'null'
title: Account Id
description: >-
ID of the Google Ads account the balance belongs to, or `null` when
`state` is `no_workspace_debt`.
example: 68b1c0d4e7b91d003c45a1f8
app_id:
anyOf:
- type: string
- type: 'null'
title: App Id
description: >-
ID of the app that owns the held account, which is not necessarily
the app in the path. The value is `null` when `state` is
`no_workspace_debt`.
example: 6820f3a4e7b91d003c45a1f2
account_status:
anyOf:
- type: string
- type: 'null'
title: Account Status
description: >-
Status of the held Google Ads account, or `null` when `state` is
`no_workspace_debt`.
example: BLOCKED
block_reason:
anyOf:
- type: string
- type: 'null'
title: Block Reason
description: >-
Why the account is held, or `null` when it is not held or the reason
is unrecorded.
example: PAYMENT_FAILED
charge_trigger_mode:
anyOf:
- type: string
- type: 'null'
title: Charge Trigger Mode
description: >-
How the account is billed. `cadence` is the recurring charge and
`threshold` is spend-triggered. The value is `null` when `state` is
`no_workspace_debt`.
example: cadence
recoverable:
type: boolean
title: Recoverable
description: >-
Whether the account is in a state Base44 can settle at all (`true`)
or not (`false`).
example: true
can_pay_now:
type: boolean
title: Can Pay Now
description: >-
Whether there is a chargeable invoice and a usable card, so settling
would go through now (`true`) or not (`false`).
example: true
requires_payment_method:
type: boolean
title: Requires Payment Method
description: >-
Whether a card has to be added or replaced before the balance can be
settled (`true`) or not (`false`).
example: false
stripe_unavailable:
type: boolean
title: Stripe Unavailable
description: >-
Whether Base44 could not reach the payment provider (`true`) or
reached it fine (`false`). When it is `true` the card check failed
closed, so `payment_method` reads `null` and `can_pay_now` reads
`false` because the check failed, not because the card is missing.
Retry rather than telling someone to add a card.
example: false
payment_method:
anyOf:
- $ref: '#/components/schemas/WorkspaceDebtPaymentMethod'
- type: 'null'
description: >-
The card on file, or `null` when the workspace has none and when the
payment provider could not be reached.
invoice:
anyOf:
- $ref: '#/components/schemas/WorkspaceDebtInvoice'
- type: 'null'
description: >-
The unpaid invoice behind the hold, or `null` when there is none to
settle and when the latest one is already paid.
type: object
required:
- state
- recoverable
- can_pay_now
- requires_payment_method
- stripe_unavailable
title: WorkspaceDebtSummary
description: Whether the workspace owes anything for Google Ads spend.
WorkspaceDebtPaymentMethod:
properties:
brand:
type: string
title: Brand
description: >-
Card brand, as the payment provider reports it. Empty when the
provider did not return one.
example: visa
last4:
type: string
title: Last4
description: >-
Last four digits of the card. Empty when the provider did not return
them.
example: '4242'
type: object
required:
- brand
- last4
title: WorkspaceDebtPaymentMethod
description: The card the workspace has on file.
WorkspaceDebtInvoice:
properties:
id:
type: string
title: Id
description: Base44's ID for the invoice.
example: 68b1c0d4e7b91d003c45a1fa
status:
type: string
title: Status
description: >-
Where the invoice stands. `FAILED` is an invoice whose charge did
not go through, and `PENDING` is one Base44 is still collecting.
example: FAILED
billing_type:
type: string
title: Billing Type
description: >-
Which billing run produced the invoice. `weekly` is the recurring
charge, `reconciliation` trues up a period, `threshold` is
spend-triggered, `google_monthly` mirrors an invoice Google issued,
and `adjustment` is a manual correction.
example: weekly
period_start:
type: string
title: Period Start
description: First day of the spend the invoice covers, as `YYYY-MM-DD`.
example: '2026-08-18'
period_end:
type: string
title: Period End
description: Last day of the spend the invoice covers, as `YYYY-MM-DD`.
example: '2026-08-24'
amount_micros:
type: integer
title: Amount Micros
description: Amount owed in micros of `currency_code`, so `43500000` is 43.50.
example: 43500000
currency_code:
type: string
title: Currency Code
description: Currency of `amount_micros` as a three-letter ISO 4217 code.
example: USD
failed_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Failed At
description: >-
When the charge last failed, or `null` on an invoice that has not
been attempted or is still pending.
example: '2026-08-25T04:12:00Z'
type: object
required:
- id
- status
- billing_type
- period_start
- period_end
- amount_micros
- currency_code
title: WorkspaceDebtInvoice
description: The unpaid Google Ads invoice behind a workspace's billing hold.
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: api_key
description: Personal API key.
````