> ## 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

> <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 or a workspace API key. A workspace API key acts as the workspace owner.</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>



## 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:
  - PersonalAccessTokenAuth: []
paths:
  /api/apps/{app_id}/google-ads/conversion-mappings:
    post:
      summary: Create Google Ads conversion mapping
      description: >-
        <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 or a workspace API key. A
        workspace API key acts as the workspace owner.</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>
      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:
              $ref: '#/components/schemas/ConversionMappingCreatePayload'
            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 or the app does not exist. A
            missing app and an app you cannot reach are deliberately the same
            answer. Marketing setup, campaign edits, generation and resuming
            also return `app_marketing_not_allowed` when the app's owning
            workspace has the FERPA designation. Historical reads, pausing,
            deletion and financial settlement remain available.
        '404':
          description: The account does not belong to this app.
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '429':
          description: >-
            `rate_limited`: The base limit is 300 requests in a minute from your
            account, shared across every Google Ads write that doesn't name its
            own limit. Some workspaces have a higher limit. `X-RateLimit-Limit`
            reports the enforced limit. Retry after `Retry-After` seconds. The
            `X-RateLimit-*` headers report the budget left.
          content:
            application/json:
              examples:
                rate_limited:
                  summary: rate_limited
                  value:
                    error:
                      code: rate_limited
                      message: Rate limit exceeded.
                      details: {}
              schema:
                $ref: '#/components/schemas/StandardErrorEnvelope'
      security:
        - PersonalAccessTokenAuth:
            - full_access
        - WorkspaceApiKeyAuth:
            - full_access
        - WorkspaceApiKeyBearerAuth:
            - full_access
components:
  schemas:
    ConversionMappingCreatePayload:
      properties:
        entity_name:
          type: string
          title: Entity Name
          description: Name of the app entity whose write this goal belongs to.
          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.
          default: create
          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`, `SIGN_UP`, or `LEAD`. The value
            is stored as sent and not checked against Google's list.
          default: ''
          example: PURCHASE
        conversion_action_id:
          type: string
          title: Conversion Action Id
          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.
          default: ''
          example: '7654321'
        value_field:
          type: string
          title: Value Field
          description: >-
            Field on the entity record holding the conversion amount. The wiring
            instructions fall back to `amount` when it is empty.
          default: ''
          example: total_price
        currency_field:
          type: string
          title: Currency Field
          description: >-
            Field on the entity record holding the currency code. The wiring
            instructions fall back to `USD` when it is empty.
          default: ''
          example: currency
        id_field:
          type: string
          title: Id Field
          description: >-
            Field on the entity record holding the order ID Google dedupes on.
            The wiring instructions fall back to `id` when it is empty.
          default: ''
          example: order_number
        is_enabled:
          type: boolean
          title: Is Enabled
          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
      type: object
      required:
        - entity_name
      title: ConversionMappingCreatePayload
    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, 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
    StandardErrorEnvelope:
      properties:
        error:
          $ref: '#/components/schemas/StandardError'
          description: What went wrong.
      type: object
      required:
        - error
      title: StandardErrorEnvelope
      description: The error body returned in the standard envelope.
    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
    StandardError:
      properties:
        code:
          type: string
          title: Code
          description: >-
            Stable machine-readable cause of the failure. Match on this, not on
            `message`.
          example: not_found
        message:
          type: string
          title: Message
          description: Human-readable explanation. It isn't a stable contract.
          example: App not found
        details:
          additionalProperties: true
          type: object
          title: Details
          description: >-
            Structured context for the failure, or an empty object when there's
            none.
          example: {}
      type: object
      required:
        - code
        - message
      title: StandardError
  securitySchemes:
    PersonalAccessTokenAuth:
      type: http
      scheme: bearer
      description: >-
        Personal access token, sent as `Authorization: Bearer <token>`. Each
        operation lists the permission it needs: `read_only` or `full_access`. A
        full-access token can call every operation. A read-only token can call
        only the operations that list `read_only`; anything else returns 403
        `read_only_credential_route_not_allowed`.
    WorkspaceApiKeyAuth:
      type: apiKey
      in: header
      name: api_key
      description: >-
        Workspace API key, sent as `api_key: <key>`. Each operation that accepts
        one lists what the key needs: a permission, `read_only` or
        `full_access`, like a personal access token, or a scope. A key without
        the scope gets 403 `workspace_api_key_scope_required`.
    WorkspaceApiKeyBearerAuth:
      type: http
      scheme: bearer
      description: >-
        Workspace API key, sent as `Authorization: Bearer <key>`. Accepted
        wherever `api_key` is, with the same permission.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.