> ## 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.
# Create Google Ads conversion mapping
> This API is in beta. Endpoints, fields, and behavior may still change, so avoid depending on it in production.
Creates a conversion mapping on one of the app's Google Ads accounts.
A conversion mapping records that one of the account's Google Ads goals belongs to an entity write in the app, so `Order.create` is the app event behind the `PURCHASE` goal. Base44 reads mappings to decide whether a campaign is ready to launch, and to offer goals in the dashboard.
Point the mapping at a goal in one of two ways. Set `conversion_action_id` to name a specific goal, or set `conversion_type` to match whichever goal on the account carries that category. Setting both means the explicit ID wins. Pass the account in the `account_id` query parameter, and an account belonging to another app returns a 404 even when it sits in the same workspace.
An enabled mapping that resolves to a real goal is what makes Base44 treat the account's conversion events as configured, which affects [Get launch readiness](/api-reference/get-google-ads-launch-readiness). Send `is_enabled` as `false` to record the mapping without that effect.
This creates a new mapping every time you call it. Nothing keeps one mapping per entity and goal, so a retried request leaves you with duplicates. Read [List conversion mappings](/api-reference/list-google-ads-conversion-mappings) first and use [Update conversion mapping](/api-reference/update-google-ads-conversion-mapping) when the mapping already exists.
A mapping does not report conversions on its own. Nothing fires a conversion when the mapped entity is written. The app has to fire it in the browser with `gtag('event', 'conversion', ...)`, or you report it from the server with [Upload conversions](/api-reference/upload-google-ads-conversions).
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. Send only the fields documented here. Other request fields are not supported and their behavior can change.
## OpenAPI
````yaml /developers/references/app-management/app-management-openapi.json post /api/apps/{app_id}/google-ads/conversion-mappings
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/conversion-mappings:
post:
summary: Create Google Ads conversion mapping
description: >-
This API is in beta. Endpoints, fields, and behavior may still
change, so avoid depending on it in production.
Creates a conversion mapping on one of the app's Google Ads accounts.
A conversion mapping records that one of the account's Google Ads goals
belongs to an entity write in the app, so `Order.create` is the app
event behind the `PURCHASE` goal. Base44 reads mappings to decide
whether a campaign is ready to launch, and to offer goals in the
dashboard.
Point the mapping at a goal in one of two ways. Set
`conversion_action_id` to name a specific goal, or set `conversion_type`
to match whichever goal on the account carries that category. Setting
both means the explicit ID wins. Pass the account in the `account_id`
query parameter, and an account belonging to another app returns a 404
even when it sits in the same workspace.
An enabled mapping that resolves to a real goal is what makes Base44
treat the account's conversion events as configured, which affects [Get
launch readiness](/api-reference/get-google-ads-launch-readiness). Send
`is_enabled` as `false` to record the mapping without that effect.
This creates a new mapping every time you call it. Nothing
keeps one mapping per entity and goal, so a retried request leaves you
with duplicates. Read [List conversion
mappings](/api-reference/list-google-ads-conversion-mappings) first and
use [Update conversion
mapping](/api-reference/update-google-ads-conversion-mapping) when the
mapping already exists.
A mapping does not report conversions on its own. Nothing fires
a conversion when the mapped entity is written. The app has to fire it
in the browser with `gtag('event', 'conversion', ...)`, or you report it
from the server with [Upload
conversions](/api-reference/upload-google-ads-conversions).
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. Send only the fields documented here. Other request fields are not
supported and their behavior can change.
operationId: >-
create_conversion_mapping_api_apps__app_id__google_ads_conversion_mappings_post
parameters:
- name: app_id
in: path
required: true
schema:
type: string
description: >-
ID of the app whose Google Ads conversion tracking you want to
manage.
title: App Id
description: >-
ID of the app whose Google Ads conversion tracking you want to
manage.
example: 6820f3a4e7b91d003c45a1f2
- name: account_id
in: query
required: true
schema:
type: string
description: >-
ID of the Google Ads account the mapping belongs to, as returned
in `id` by [Get Google Ads
account](/api-reference/get-google-ads-account). An account
belonging to a different app returns a 404.
title: Account Id
description: >-
ID of the Google Ads account the mapping belongs to, as returned in
`id` by [Get Google Ads
account](/api-reference/get-google-ads-account). An account
belonging to a different app returns a 404.
example: 68b1c0d4e7b91d003c45a1f8
requestBody:
required: true
content:
application/json:
schema:
title: CreateConversionMapping
type: object
required:
- entity_name
properties:
entity_name:
type: string
description: Name of the app entity whose write this goal belongs to.
example: Order
trigger_action:
type: string
description: >-
Which write on the entity the goal belongs to. Base44 uses
`create`, `update`, and `delete`, and stores any other value
as sent.
default: create
example: create
conversion_type:
type: string
description: >-
Which kind of conversion this is, using Google's category
vocabulary such as `PURCHASE`, `ADD_TO_CART`, `SIGN_UP`, or
`LEAD`. The value is stored as sent and not checked against
Google's list.
example: PURCHASE
conversion_action_id:
type: string
description: >-
Google Ads' own ID for the goal to point at, as returned in
`google_action_id` by [List conversion
actions](/api-reference/list-google-ads-conversion-actions).
Send it alongside `conversion_type` and this one is matched
first, with `conversion_type` as the fallback if it matches
no goal on the account.
example: '7654321'
value_field:
type: string
description: >-
Field on the entity record holding the conversion amount.
The wiring instructions fall back to `amount` when it is
empty.
example: total_price
currency_field:
type: string
description: >-
Field on the entity record holding the currency code. The
wiring instructions fall back to `USD` when it is empty.
example: currency
id_field:
type: string
description: >-
Field on the entity record holding the order ID Google
dedupes on. The wiring instructions fall back to `id` when
it is empty.
example: order_number
is_enabled:
type: boolean
description: >-
Whether Base44 counts this mapping when it decides the
account's conversion events are configured (`true`) or
ignores it (`false`).
default: true
example: true
example:
entity_name: Order
trigger_action: create
conversion_type: PURCHASE
value_field: total_price
currency_field: currency
id_field: order_number
responses:
'200':
description: The mapping that was created.
content:
application/json:
schema:
$ref: '#/components/schemas/ConversionMappingResource'
'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.
'404':
description: The account does not belong to this app.
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
components:
schemas:
ConversionMappingResource:
properties:
id:
type: string
title: Id
description: ID of the mapping. Pass this as `mapping_id` to update or delete it.
example: 68b1c0d4e7b91d003c45a1f7
account_id:
type: string
title: Account Id
description: ID of the Google Ads account the mapping belongs to.
example: 68b1c0d4e7b91d003c45a1f8
entity_name:
type: string
title: Entity Name
description: >-
Name of the app entity whose write this goal belongs to, as returned
by [List entity schemas](/api-reference/list-entity-schemas). It is
empty on a mapping Base44 created from a conversion it verified
firing in the app code, because a client-side conversion has no
entity behind it.
example: Order
trigger_action:
type: string
title: Trigger Action
description: >-
Which write on the entity the goal belongs to. Base44 uses `create`,
`update`, and `delete`, and stores any other value as sent.
example: create
conversion_type:
type: string
title: Conversion Type
description: >-
Which kind of conversion this is, using Google's category vocabulary
such as `PURCHASE`, `ADD_TO_CART`, `BEGIN_CHECKOUT`, `SIGN_UP`,
`LEAD`, or `CONTACT`. Empty when nothing was set for it. The value
is stored as sent and not checked against Google's list.
example: PURCHASE
conversion_action_id:
type: string
title: Conversion Action Id
description: >-
Google Ads' own ID for the goal this mapping points at, as returned
in `google_action_id` by [List conversion
actions](/api-reference/list-google-ads-conversion-actions). Empty
when nothing was set for it. A mapping can carry both this and
`conversion_type`, and this one is matched first. If it matches no
goal on the account, which happens when the goal was recreated in
Google Ads under a new ID, the mapping falls back to matching on
`conversion_type`.
example: '7654321'
value_field:
type: string
title: Value Field
description: >-
Field on the entity record holding the conversion amount. It is read
only when writing the wiring instructions for the AI builder, which
falls back to `amount` when this is empty.
example: total_price
currency_field:
type: string
title: Currency Field
description: >-
Field on the entity record holding the currency code. Same use as
`value_field`, and the instructions fall back to `USD` when this is
empty.
example: currency
id_field:
type: string
title: Id Field
description: >-
Field on the entity record holding the order ID Google dedupes on.
Same use as `value_field`, and the instructions fall back to `id`
when this is empty.
example: order_number
is_enabled:
type: boolean
title: Is Enabled
description: >-
Whether Base44 counts this mapping when it decides a campaign's
conversion events are configured (`true`) or ignores it (`false`).
example: true
created_date:
type: string
format: date-time
title: Created Date
description: When the mapping was created.
example: '2026-08-25T11:20:00Z'
updated_date:
type: string
format: date-time
title: Updated Date
description: When the mapping was last changed.
example: '2026-08-25T14:05:00Z'
type: object
required:
- id
- account_id
- entity_name
- trigger_action
- conversion_type
- conversion_action_id
- value_field
- currency_field
- id_field
- is_enabled
- created_date
- updated_date
title: ConversionMappingResource
description: A conversion goal tied to an entity write in the app.
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
type: object
required:
- loc
- msg
- type
title: ValidationError
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: api_key
description: Personal API key.
````