Reddit Conversions

This guide covers how to submit offline conversions to Reddit Ads through the TNT Growth API.

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 a Conversion

Endpoint

POST /api/reddit/events/add

Request Body Schema

Field	Type	Required	Description
pixelId	string	Yes	Your Reddit Pixel ID (provided during onboarding)
eventType	object	Yes	The type of conversion event (see below)
eventTime	number	No	Unix timestamp (seconds) of when the event occurred
clickId	string	No	Reddit click ID captured from the ad click
eventSourceUrl	string	No	The URL where the event took place
testId	string	No	Reddit test mode ID for verifying in Events Manager
userData	object	No	Customer identifiers for matching (see below)
eventMetadata	object	No	Conversion details like value and products (see below)
utmSource	string	No	UTM source parameter (e.g. reddit) — stored for attribution reporting
utmMedium	string	No	UTM medium parameter (e.g. cpc) — stored for attribution reporting
utmCampaign	string	No	UTM campaign name — stored for attribution reporting
utmTerm	string	No	UTM search keyword — stored for attribution reporting
utmContent	string	No	UTM content parameter (ad/creative variant) — stored for attribution reporting

Event Type

Field	Type	Required	Description
tracking_type	string	Yes	One of the tracking types listed below
custom_event_name	string	No	Custom event name (required when tracking_type is Custom)

Tracking types: PageVisit, ViewContent, Search, AddToCart, AddToWishlist, Purchase, Lead, SignUp, Custom

User Data Fields

Field	Type	Description
email	string	Customer email address
phone	string	Customer phone number
ipAddress	string	IP address of the customer
userAgent	string	Browser user agent string
externalId	string	Your internal customer ID
idfa	string	Apple ID For Advertisers
aaid	string	Android Advertising ID
uuid	string	Unique user identifier
screenDimensions	object	{ width: number, height: number }
dataProcessingOptions	object	Privacy compliance options (see below)

Event Metadata

Field	Type	Description
itemCount	number	Number of items in the conversion
currency	string	Currency code (e.g. USD)
valueDecimal	number	Monetary value of the conversion
conversionId	string	Your internal conversion/order ID
products	array	Array of { id, name, category } objects

Example Request

curl -X POST https://flex.tntgrowth.io/api/reddit/events/add \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "pixelId": "t2_abc123def",
    "eventType": {
      "tracking_type": "Purchase"
    },
    "eventTime": 1778043599,
    "clickId": "rdt_abc123...",
    "eventSourceUrl": "https://example.com/thank-you",
    "userData": {
      "email": "customer@example.com",
      "phone": "+15551234567",
      "externalId": "cust-12345"
    },
    "eventMetadata": {
      "currency": "USD",
      "valueDecimal": 150.00,
      "itemCount": 2,
      "conversionId": "order-12345"
    },
    "utmSource": "reddit",
    "utmMedium": "cpc",
    "utmCampaign": "awareness-q2",
    "utmTerm": "treatment options",
    "utmContent": "promoted-post-variant-b"
  }'

Example Response

{
  "message": "Conversion successfully queued for Example Client",
  "data": {
    "submissionId": "8f3c2d10-7e6b-4a51-9d8c-3b2e1f0a9b8c"
  }
}

Checking Submission Status

After submitting a conversion, use the submission ID to check processing status.

Endpoint

GET /api/conversions/submissions/:submissionId

Example Request

curl https://flex.tntgrowth.io/api/conversions/submissions/8f3c2d10-7e6b-4a51-9d8c-3b2e1f0a9b8c \
  -H "x-api-key: YOUR_API_KEY"

Example Response

{
  "id": "8f3c2d10-7e6b-4a51-9d8c-3b2e1f0a9b8c",
  "source": "REDDIT",
  "externalAccountId": "t2_abc123def",
  "expectedCount": 1,
  "createdAt": "2026-05-11T12:00:00.000Z",
  "scheduledFor": null,
  "counts": {
    "success": 1,
    "failed": 0
  },
  "status": "complete"
}

Status Values

Status	Description
pending	Conversion is queued and waiting to be processed
pending_delivery	Submission is scheduled for future delivery — the scheduledFor field carries the ISO-8601 fire timestamp. Currently only emitted by Google Ads ingest paths; Reddit submissions never enter this state.
complete	Conversion processed successfully
complete_with_errors	Processing finished but some conversions failed — use GET /api/conversions/reddit/failed?submissionId=<id> to fetch the actual error messages
stalled	Processing has not progressed — contact support

The scheduledFor field is always null for Reddit submissions and is included only for schema parity with Google Ads, which uses it for deferred delivery.

Inspecting Failed Conversions In Your Batch

When a submission ends with complete_with_errors, the submission status endpoint surfaces only the count of failed rows. Fetch the actual error messages with:

GET /api/conversions/reddit/failed?submissionId=<submissionId>

The response payload mirrors the Google Ads failed-conversion shape — see Google Ads → Inspecting Failed Conversions In Your Batch.

Data Processing Options

For privacy compliance (e.g. CCPA), you can include data processing options in userData:

{
  "dataProcessingOptions": {
    "modes": ["LDU"],
    "country": "US",
    "region": "CA"
  }
}

Best Practices

• Include clickId when available — Reddit click IDs provide the strongest attribution signal
• Send userData with email and/or phone to improve match rates for offline events
• Use accurate timestamps — eventTime should reflect when the event actually occurred
• Include conversionId in eventMetadata for deduplication on Reddit's side
• Poll with a delay — wait 30-60 seconds after submission before checking status
• Use Custom tracking type with a custom_event_name for events that don't map to standard types