Google Ads Conversions

This guide covers how to submit offline conversions to Google Ads through the TNT Growth API, check submission status, and investigate per-conversion results.

Authentication

All requests require an x-api-key header with your client-specific API key provided by TNT Growth.

-H "x-api-key: YOUR_API_KEY"

Submitting Conversions

Endpoint

POST /google/conversions/add

Request

Send an array of conversion objects. Each request accepts a maximum of 100 conversions. For larger batches, chunk your data into groups of 100 and submit multiple requests.

Request Body Schema

Field	Type	Required	Description
customerId	string	Yes	Google Ads customer ID (no dashes)
conversionActionId	string	Yes	The conversion action ID from Google Ads
gclid	string	Yes	The Google Click ID captured from the ad click
timeStamp	number	Yes	Unix timestamp (seconds) of when the conversion occurred
conversionValue	number	Yes	Monetary value of the conversion

Example Request

curl -X POST https://api.tntgrowth.io/google/conversions/add \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '[
    {
      "customerId": "4482546575",
      "conversionActionId": "7567171084",
      "gclid": "Cj0KCQjwh-HPBhCIARIsAC0p3ce...",
      "timeStamp": 1778043599,
      "conversionValue": 1
    },
    {
      "customerId": "4482546575",
      "conversionActionId": "7567171084",
      "gclid": "EAIaIQobChMI4Yb...",
      "timeStamp": 1778043610,
      "conversionValue": 50
    }
  ]'

Example Response

{
  "message": "Conversions queued successfully",
  "submissionIds": [
    "sub_abc123def456"
  ],
  "statusUrls": [
    "/conversions/submissions/sub_abc123def456"
  ]
}

The response includes submissionIds you can use to track the status of your submission, along with statusUrls for convenience.

Checking Submission Status

After submitting conversions, you can poll the submission status to determine whether processing is complete.

Endpoint

GET /conversions/submissions/:submissionId

Path Parameters

Parameter	Type	Description
submissionId	string	The submission ID from the submit response

Example Request

curl https://api.tntgrowth.io/conversions/submissions/sub_abc123def456 \
  -H "x-api-key: YOUR_API_KEY"

Example Response

{
  "submissionId": "sub_abc123def456",
  "status": "complete",
  "totalConversions": 2,
  "successCount": 2,
  "failedCount": 0,
  "createdAt": "2026-05-11T12:00:00.000Z",
  "completedAt": "2026-05-11T12:00:45.000Z"
}

Status Values

Status	Description
pending	Conversions are queued and waiting to be processed
complete	All conversions processed successfully
complete_with_errors	Processing finished but some conversions failed
stalled	Processing has not progressed — contact support

Detailed Per-Conversion Status (Batch Lookup)

For granular visibility into individual conversion results, use the batch status endpoint. This is especially useful when a submission completes with errors and you need to identify which specific conversions failed.

Endpoint

POST /google/conversions/status

Request

Send an array of conversion identifiers. Each request accepts a maximum of 100 conversions.

Request Body Schema

Field	Type	Required	Description
customer_id	string	Yes	Google Ads customer ID (no dashes)
gclid	string	Yes	The Google Click ID
conversion_action_id	string	Yes	The conversion action ID from Google Ads

Example Request

curl -X POST https://api.tntgrowth.io/google/conversions/status \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '[
    {
      "customer_id": "4482546575",
      "gclid": "Cj0KCQjwh-HPBhCIARIsAC0p3ce...",
      "conversion_action_id": "7567171084"
    },
    {
      "customer_id": "4482546575",
      "gclid": "EAIaIQobChMI4Yb...",
      "conversion_action_id": "7567171084"
    }
  ]'

Example Response

{
  "results": [
    {
      "customer_id": "4482546575",
      "gclid": "Cj0KCQjwh-HPBhCIARIsAC0p3ce...",
      "conversion_action_id": "7567171084",
      "status": "processed",
      "message": "Conversion uploaded successfully to Google Ads"
    },
    {
      "customer_id": "4482546575",
      "gclid": "EAIaIQobChMI4Yb...",
      "conversion_action_id": "7567171084",
      "status": "partial_failure",
      "message": "CLICK_NOT_FOUND: The click ID could not be matched to an existing Google Ads click"
    }
  ]
}

Per-Conversion Status Values

Status	Description
processed	Conversion uploaded successfully to Google Ads
partial_failure	Google accepted the request but reported an error for this conversion
failed_pre_google	Conversion failed validation before reaching Google Ads
not_found	No matching conversion record found in the system

The message field provides specific error details when the status is not processed.

Best Practices

• Chunk large batches into groups of 100 conversions per request
• Store submission IDs from responses for status tracking
• Poll with a delay — wait 30-60 seconds after submission before checking status, as conversions are processed asynchronously
• Use batch status for debugging — when a submission reports complete_with_errors, use the per-conversion status endpoint to identify exactly which conversions failed and why
• Validate GCLIDs — ensure the Google Click IDs you submit are accurate and correspond to real ad clicks
• Timestamp accuracy — conversion timestamps must not be in the future; use the actual time the conversion event occurred