CAPI v2 to v3 Migration

Reddit is launching Conversions API v3, which introduces breaking changes to the current request payload structure. This change requires advertisers using Conversions API v3 to consolidate their integration to comply with the new structure.

We encourage advertisers to migrate to take advantage of new features and long-term support.

What’s changing

Endpoint path

v2

https://ads-api.reddit.com/api/v2.0/conversions/events/{{Pixel ID}}

v3

https://ads-api.reddit.com/api/v3/pixels/{{Pixel ID}}/conversion_events

Request structure

v2

{
  "events": [
    // ...event data
  ]
}

v3

{
  "data": {
    "events": [
      // ...event data
    ]
  }
}

New nested structure of data node wrapping the original request payload. New nested structure with a data node wrapping the original request payload.

Request parameters

Unlisted fields remain unchanged between versions.

v2	v3
test_mode	deprecated, now supported through test_id
event_at	changed to integer type, representing the Unix epoch in milliseconds
event_at_ms	deprecated, now supported through event_at
action_source	changed to a required field
event_type	renamed to type
event_type.tracking_type	updated enum to UPPER_SNAKE_CASE format (e.g., PAGE_VISIT). See standard events.
event_metadata	renamed to metadata
event_metadata.value	changed to double type, representing the base unit of the currency
event_metadata.value_decimal	deprecated, now supported through value
user.opt_out	deprecated, now supported through user.data_processing_options
N/A	new, event_source_url allows domains to be assigned to events, enabling domain detection in the Events Manager

Standard events

v2	v3
PageVisit	PAGE_VISIT
ViewContent	VIEW_CONTENT
Search	SEARCH
AddToCart	ADD_TO_CART
AddToWishlist	ADD_TO_WISHLIST
Purchase	PURCHASE
Lead	LEAD
SignUp	SIGN_UP
Custom	CUSTOM

Response codes

Conversions API now supports a wide range of HTTP status codes. You can refer to Post Conversion Events for the response format corresponding to each status code. Learn more about error handling and possible resolutions.

Step-by-step migration

1. Update endpoint path to /api/v3/pixels/{{Pixel ID}}/conversion_events.
2. Wrap your JSON request payload in a data object node (i.e., { "data": // your current payload goes here }).
3. Update your parameters.
   • Remove test_mode
   • Convert event_at to Unix epoch in milliseconds or rename event_at_ms to event_at
   • Label your event with a permitted action_source
   • Rename event_type to type and event_metadata to metadata
   • Change the value format of type.tracking_type to UPPER_SNAKE_CASE (e.g., PageVisit to PAGE_VISIT)
   • Convert metadata.value to a double or rename metadata.value_decimal to metadata.value
   • Replace user.opt_out with user.data_processing_options
   • (Optional, WEBSITE events only) Provide the page URL for event_source_url
     Domain will be parsed from the URL. Provide a URL with the click ID appended for better attribution and match rate.

4. Verify events in Event Testing.
5. Review the latest response structure and error handling solutions.

Things to know

• We accept conversion events from versions of CAPI. We strongly discourage sending the same event to both versions of CAPI (dual-sending).
• We recommend a percentage rollout when migrating production traffic from v2 to v3 to minimize event loss due to misconfiguration.
• Existing bearer tokens are still valid, and you don’t need to generate a new one for v3.