---
title: "Create Google Ads conversion mapping"
method: POST
path: "/api/apps/{app_id}/google-ads/conversion-mappings"
---

# Create Google Ads conversion mapping

`POST /api/apps/{app_id}/google-ads/conversion-mappings`

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

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.

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

<Warning>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).</Warning>

<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. Send only the fields documented here. Other request fields are not supported and their behavior can change.</Warning>

## Path parameters

- `app_id` string, required — ID of the app whose Google Ads conversion tracking you want to manage.

## Query parameters

- `account_id` string, required — 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.

## Request body

- object
  - `entity_name` string, required — Name of the app entity whose write this goal belongs to.
  - `trigger_action` string — Which write on the entity the goal belongs to. Base44 uses `create`, `update`, and `delete`, and stores any other value as sent.
  - `conversion_type` string — 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.
  - `conversion_action_id` string — 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.
  - `value_field` string — Field on the entity record holding the conversion amount. The wiring instructions fall back to `amount` when it is empty.
  - `currency_field` string — Field on the entity record holding the currency code. The wiring instructions fall back to `USD` when it is empty.
  - `id_field` string — Field on the entity record holding the order ID Google dedupes on. The wiring instructions fall back to `id` when it is empty.
  - `is_enabled` boolean — Whether Base44 counts this mapping when it decides the account's conversion events are configured (`true`) or ignores it (`false`).

## Response `200`

The mapping that was created.

- ConversionMappingResource — A conversion goal tied to an entity write in the app.
  - `id` string, required — ID of the mapping. Pass this as `mapping_id` to update or delete it.
  - `account_id` string, required — ID of the Google Ads account the mapping belongs to.
  - `entity_name` string, required — 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.
  - `trigger_action` string, required — Which write on the entity the goal belongs to. Base44 uses `create`, `update`, and `delete`, and stores any other value as sent.
  - `conversion_type` string, required — 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.
  - `conversion_action_id` string, required — 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`.
  - `value_field` string, required — 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.
  - `currency_field` string, required — 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.
  - `id_field` string, required — 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.
  - `is_enabled` boolean, required — Whether Base44 counts this mapping when it decides a campaign's conversion events are configured (`true`) or ignores it (`false`).
  - `created_date` string, date-time, required — When the mapping was created.
  - `updated_date` string, date-time, required — When the mapping was last changed.

## Other responses

- `401` — Missing or invalid credentials.
- `403` — 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` — The account does not belong to this app.
- `422` — Validation Error

---

[API](https://skmtc.dev/adexad/apis/base44-app-management-api.md) · [All operations](https://skmtc.dev/adexad/apis/base44-app-management-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/adexad/base44-app-management-api/revisions/7f5ce8287501/schema)