Sign in

Get Google Ads workspace debt

<Info>This API is in beta. Endpoints, fields, and behavior may still change, so avoid depending on it in production.</Info>

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.

<Note>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.</Note>

<Note>This endpoint accepts a personal API key. Workspace API keys are not authorized for it and are rejected with a 403.</Note>

<Warning>The response includes fields beyond the ones documented here. Don't rely on undocumented response fields, as they can change at any time.</Warning>

get/api/apps/{app_id}/google-ads/billing/workspace-debt

Path parameters

app_idstring required

ID of the app whose Google Ads campaigns to manage.

ID of the app whose Google Ads campaigns to manage.

Response

What the workspace owes, and whether it can be settled.

statestring required

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.

account_idstring nullable

ID of the Google Ads account the balance belongs to, or null when state is no_workspace_debt.

app_idstring nullable

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.

account_statusstring nullable

Status of the held Google Ads account, or null when state is no_workspace_debt.

block_reasonstring nullable

Why the account is held, or null when it is not held or the reason is unrecorded.

charge_trigger_modestring nullable

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.

recoverableboolean required

Whether the account is in a state Base44 can settle at all (true) or not (false).

can_pay_nowboolean required

Whether there is a chargeable invoice and a usable card, so settling would go through now (true) or not (false).

requires_payment_methodboolean required

Whether a card has to be added or replaced before the balance can be settled (true) or not (false).

stripe_unavailableboolean required

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 response

{
  "state": "payable",
  "account_id": "68b1c0d4e7b91d003c45a1f8",
  "app_id": "6820f3a4e7b91d003c45a1f2",
  "account_status": "BLOCKED",
  "block_reason": "PAYMENT_FAILED",
  "charge_trigger_mode": "cadence",
  "recoverable": true,
  "can_pay_now": true,
  "payment_method": {
    "brand": "visa",
    "last4": "4242"
  },
  "invoice": {
    "id": "68b1c0d4e7b91d003c45a1fa",
    "status": "FAILED",
    "billing_type": "weekly",
    "period_start": "2026-08-18",
    "period_end": "2026-08-24",
    "amount_micros": 43500000,
    "currency_code": "USD",
    "failed_at": "2026-08-25T04:12:00Z"
  }
}

Changes

Changed in 1 of the 14 revisions of this API.1