POST /providerapi/offlineconversion

The POST /providerapi/offlineconversion endpoint enables you to upload user-level offline conversions, which can include use cases such as attributing in-store sales, place visits, merchant product catalog items, or custom events.

TIP: For general information about offline measurement, FAQs, and other details, see Offline conversion events.

Request preparation guidelines

NOTE: Some IDs, such as raw UID2s, raw EUIDs, and their respective tokens, are case sensitive. Pass all IDs and tokens without changing the case. Mismatched IDs can cause ID parsing or token decryption errors.

Here are some recommendations to help you structure your requests effectively:

• Since event names are displayed to advertisers in the platform UI, be sure to use consistent and easy-to-read patterns for naming your offline conversion events.
• When uploading product catalog data for merchants, be sure to include additional fields required beyond the standard schema. For example, MerchantId, EventName, OrderId, and LineItems.
• Upload individual IDs by listing them as item objects in the Items array.
  • If you provide an ImpressionId value in the Items array, no other ID is required.
  • Otherwise, each item object in the Items array must have at least one supported ID type.
• Upload multiple IDs grouped together in either of the following ways:
  • Using a UserIdArray array with up to 20 IDs per array.
  • Listing IDs of different ID types within a single item object. To upload IDs with the same ID type, add another item object to the Items array or use the UserIdArray property.

IMPORTANT: This endpoint is designed to receive offline or batched events. Advertisers are expected to filter out non-consented events before submission. For details, see Privacy Settings object properties.

Data upload guidelines

Here are some recommendations for uploading data for offline measurement:

• The total request size may not exceed 28.6 MB. There's no limit on the number of events you can send.
• Consolidate your data into as few API calls as possible. For example, instead of sending 3,000 conversion events in 3,000 separate calls, use a single API request to send the entire batch of 3,000 offline conversions.
• To ensure that the data for sales measurement is captured and attributed properly, be sure to follow these guidelines (based on the event date specified in the Items.TimestampUtc property):
  • Send data to The Trade Desk as soon as possible, ideally, within 1 to 3 days of the transaction date.
  • Avoid uploading data older than 25 days after the date the event occurred. This helps us account for any lag time that we need after ingesting the data to run attribution properly for any month in the calendar year for a 30-day look-back.

See also FAQs in Offline conversion events.

Environment

This endpoint uses a specific environment for offline attribution. The following table shows the environment, path, and full endpoint URL.

Request syntax

The following sections explain the syntax for different ways to include user IDs in the Items array:

• Individually (one ID per object)
• Grouped (multiple IDs within a single object)

TIP: Start by reviewing the syntax and field usage guidelines in Request object properties. Then, refer to these resources for real-world use cases and request body examples: Conversion event data examples and Merchant event data examples.

Single user ID per object

The following example shows the POST /providerapi/offlineconversion request syntax with three conversion events. The first event uses an impression ID, which means no other ID is necessary for that item. The second event uses a placeholder for a specific different user ID type. The first two events show only required fields, the last event demonstrates how to include optional privacy settings properties.

{
   "DataProviderId": "DATA_PROVIDER_ID_PLACEHOLDER",
   "Items": [
      {
         "ImpressionID": "IMPRESSION_ID_PLACEHOLDER",
         "TrackingTagId": "TRACKING_TAG_ID_PLACEHOLDER",
         "TimestampUtc": "DATETIME_PLACEHOLDER"
         // Additional event metadata goes here.
      },
      {
         "ID_TYPE_PLACEHOLDER": "ID_STRING_PLACEHOLDER",
         "TrackingTagId": "TRACKING_TAG_ID_PLACEHOLDER",
         "TimestampUtc": "EVENT_DATETIME_PLACEHOLDER"
         // Additional event metadata goes here.
      },
      {
         "ID_TYPE_PLACEHOLDER": "ID_STRING_PLACEHOLDER",
         "TrackingTagId": "TRACKING_TAG_ID_PLACEHOLDER",
         "TimestampUtc": "EVENT_DATETIME_PLACEHOLDER",
         "PrivacySettings": [
            {
               "privacy_type": "PRIVACY_REGULATION_TYPE_PLACEHOLDER",
               "is_applicable": 1,
               "consent_string": "USER CONSENT STRING PLACEHOLDER"
            }
         ]
         // Additional event metadata goes here.
      }
   ]
}

The following example shows how to include additional metadata and custom properties.

NOTE: These fields help enrich the conversion signal but are not required for standard uploads. However, when uploading merchant product catalog items, the following fields are required: MerchantId, OrderId, EventName, and at least one line item with the item_code property.

{
   "DataProviderId": "DATA_PROVIDER_ID_PLACEHOLDER",
   "Items": [
      {
         "ID_TYPE_PLACEHOLDER": "ID_STRING_PLACEHOLDER",
         "TrackingTagId": "TRACKING_TAG_ID_PLACEHOLDER",
         "TimestampUtc": "EVENT_DATETIME_PLACEHOLDER",
         "MerchantId": "MERCHANT_ID_PLACEHOLDER",
         "ReferrerUrl": "WEBPAGE_URL_PLACEHOLDER",
         "ClientIPAddress": "CLIENT_IP_ADDRESS_PLACEHOLDER",         
         "EventName": "USER_ACTION_PLACEHOLDER",
         "Value": CONVERSION_AMOUNT_PLACEHOLDER,
         "ValueCurrency": "CURRENCY_PLACEHOLDER",
         "Country": "FULL_COUNTRY_NAME_PLACEHOLDER",
         "Region": "GEO_REGION_PLACEHOLDER",
         "NielsenDMA": METRO_AREA_CODE_PLACEHOLDER,
         "City": "CITY_NAME_PLACEHOLDER",
         "PostalCode": "ZIP_CODE_PLACEHOLDER",         
         "OrderId": "ORDER_ID_PLACEHOLDER",
         "LineItems": [
            {
               "item_code": "SKU_OR_PRODUCT_ID_PLACEHOLDER",
               "name": "PRODUCT_NAME_PLACEHOLDER",
               "price": UNIT_PRICE_PLACEHOLDER,
               "qty": NUMBER_OF_UNITS_PLACEHOLDER,
               "cat": "PRODUCT_CATEGORY_PLACEHOLDER",
               "item_brand": "ITEM_BRAND_NAME_PLACEHOLDER"              
            }
         ],
         "TD1": "CUSTOM_METADATA_1_PLACEHOLDER",
         "TD2": "CUSTOM_METADATA_2_PLACEHOLDER"
      }
   ]
}

NOTE: Any included TD1-TD10 values are automatically applied to all objects in the LineItems array.

Multiple user IDs per object

The following sections provide examples that show two valid ways to submit the same set of user IDs of different type in the Items object—one using the UserIdArray format and the other using individual ID fields.

Multiple user IDs included as an array

This POST /providerapi/offlineconversion request example demonstrates how to use the compact UserIdArray format. You can bundle multiple IDs (up to 20) into a single array of [type, id] pairs. For ID type integer mappings, see Supported ID types.

IMPORTANT: When using the UserIdArray property, you must define its structure using the UserIdArrayMetadataFormat property. This must be set to ["type", "id"]—in this exact order of values—where type is an integer mapped to the user ID type, and id is an ID value as a string. For details, see the UserIdArray property description.

{
   "DataProviderId": "DATA_PROVIDER_ID_PLACEHOLDER",
   "UserIdArrayMetadataFormat": ["type", "id"],
   "Items": [
      {
         "TrackingTagId": "TRACKING_TAG_ID_PLACEHOLDER",
         "TimestampUtc": "EVENT_DATETIME_PLACEHOLDER",
         "UserIdArray": [
            [0, "TDID_PLACEHOLDER"],
            [1, "DAID_PLACEHOLDER"],
            [2, "UID2_PLACEHOLDER"]
            [3, "UID2_TOKEN_PLACEHOLDER"],
            [4, "EUID_PLACEHOLDER"],
            [5, "EUID_TOKEN_PLACEHOLDER"]
            [6, "RAMP_ID_PLACEHOLDER"]
         ]
         // Additional event metadata goes here.
      }
   ]
}

For real-world use cases and request samples, see Conversion event data examples and Merchant event data examples.

Multiple user IDs included individually

This POST /providerapi/offlineconversion request example demonstrates how to include individual user ID fields directly within the object.

IMPORTANT: Each included ID must be of different type.

{
   "DataProviderId": "DATA_PROVIDER_ID_PLACEHOLDER",
   "Items": [
      {
         "TrackingTagId": "TRACKING_TAG_ID_PLACEHOLDER",
         "TimestampUtc": "EVENT_DATETIME_PLACEHOLDER",         
         "TDID": "TDID_PLACEHOLDER",
         "DAID": "DAID_PLACEHOLDER",
         "UID2": "UID2_PLACEHOLDER",
         "UID2_TOKEN": "UID2_TOKEN_PLACEHOLDER",
         "EUID": "EUID_PLACEHOLDER",
         "EUID_TOKEN": "EUID_TOKEN_PLACEHOLDER",
         "RampID": "RAMP_ID_PLACEHOLDER"
         // Additional event metadata goes here.
      }
   ]
}

For real-world use cases and request samples, see Conversion event data examples and Merchant event data examples.

Request object properties

The following table lists the POST /providerapi/offlineconversion request object properties.

Items object properties

Here's what you need to know about the object properties in the Items array:

• The Items object can contain multiple ID types, but only one ID of the same type is allowed in each object of the Items object array. For example, you must not include two TDID values. See also Multiple user IDs included individually.
• If you need to include multiple user IDs of the same kind in the same item object, use the UserIdArray array.
• You can mix formats for passing single and multiple user IDs within the same request.
• If an ImpressionId value is provided for an item, no user IDs are required. The TDID of the item will be set to an all-zero GUID.
• Product catalog data for merchants requires additional fields beyond the standard schema. For example, MerchantId, EventName, OrderId, and LineItems. See also Merchant event data examples.
• Any included TD1-TD10 values are automatically applied to all objects in the LineItems array.

For real-world use cases and request samples, see Conversion event data examples and Merchant event data examples.

The following table lists the Items object properties for offline conversion events.

* © 2026, The Nielsen Company (US), LLC. The DMA® data is used pursuant to a license from The Nielsen Company (US), LLC. Any use and/or reproduction of these materials without the express written consent of The Nielsen Company (US), LLC, is strictly prohibited. DMA® data is valid for the period 2025 - 2026. DMA® is a registered service mark of The Nielsen Company (US), LLC and is used pursuant to license.

Supported ID types

The following table lists the ID types currently supported in the Items object, including their corresponding integer mapping values required when uploading IDs as an array (UserIdArray).

NOTE: If you provide an ImpressionId value in the Items array, no other ID is required. Otherwise, each item object in the Items array must have at least one supported ID type.

For real-world use cases and request samples, see Conversion event data examples and Merchant event data examples.

Event mapping

The Trade Desk provides a list of events that you can track without any additional configuration. Here's what you need to know about the event names list:

• The list is ordered from bottom-funnel actions, such as purchases (which are most desired), to top-funnel actions (that occur less consistently or are less critical).
• Some event names have similar functions (for example, initiatecheckout and startcheckout) and are shown together. You can use whichever one, depending on your business needs.
• To configure and manage additional events as a merchant with a product catalog, you need to use the platform UI. For details, see Event Tracking in the Knowledge Portal.

Privacy Settings object properties

IMPORTANT: Since this endpoint is designed to receive offline or batched events, advertisers are expected to filter out non-consented events before submission. This setting is optional and intended only for cases where filtering non-consented events is not feasible for the advertiser.

The following table lists the PrivacySettings object properties.

Line Items object properties

Here's what you need to know about the LineItems array:

• This object is required for uploading product catalog data for merchants.
• Any included TD1-TD10 values are automatically applied to all objects in the LineItems array.

The following table lists the LineItems object properties that contain merchant product catalog line item information.

For real-world use cases and request samples, see Merchant event data examples.

Versioning

Two versions of the Data API are available. The difference is the response format. For details, see API versions. This documentation includes both versions of the response error information.

API versions

Version 2 of the Data API is available, and includes improvements to the API response. Version 1 is fully supported, but is being deprecated. We recommend upgrading as soon as possible.

To use version 2, see Response (v2).

For details on the version timeline, see Data API version 2 with improved error handling and response format.

The following table compares the two versions.

Using the custom header

To use version 2, add the following custom header:

• Header name: TTD-Version
• Value: 2

For example: TTD-Version: 2

NOTE: The custom header is required only if you want to use a version that is not the default. Valid values for this header are 1 or 2, and if you're using the default version, currently version 1, there is no need to include the extra header.

What you need to know

Here's what you need to know about returned responses for both versions:

• If the entire request fails with no items processed, an error response is returned.
• If the FailedLines array is empty, all items succeeded.

IMPORTANT: A 200 OK status code does not indicate complete success. Always check the FailedLines array for line-level errors.

Response (v2)

To use version 2, you'll need to:

• Use a new custom header. For details, see Using the custom header.
• Update how you parse error responses. The new responses are in JSON format.

The following sections provide details about success and failed responses for version 2, including response format, response examples, and error messaging.

Success response (v2)

If the request is successful, the response has an HTTP status code of 200 OK and includes a FailedLines array with details of any items that were not processed.

Success response example (v2)

The following is an example of a success response with one FailedLines entry:

{
  "FailedLines": [
    {
      "ErrorCode": "ItemDeserializationError",
      "Message": "Item number 2: A deserialization error occurred. Could not find member 'xTDID' on object of type 'AdvertiserDataItem'. Path 'Items[1].xTDID', line 14, position 16.",
      "ItemNumber": "2"
    }
  ]
}

Success response object properties

The following table lists the object properties for a successful response.

FailedLine object properties (v2)

The following table lists the FailedLine object properties for version 2 of the Data APIs.

FailedLine error codes and messages (v2)

The following table lists the error codes that might be returned from this endpoint in a FailedLine entry in the FailedLines object, with the reason for each error. This information is for version 2 of the Data API.

Failed response (v2)

If the request fails with no lines processed, a failed response is returned.

Failed response example (v2)

The error response is JSON and includes ErrorCode and Message properties. For example, the following response would return a 403 Forbidden HTTP status code:

{
  "ErrorCode": "TargetingDataLimitReached",
  "Message": "The maximum allowed targeting data elements limit for the specified advertiser/data provider has been reached."
}

Failed response object properties (v2)

The following table lists the object properties for a failed response.

Failed response error codes and messages (v2)

The following table provides a list of common failed response errors and their respective HTTP status codes.

IMPORTANT: When the rate limit for an API endpoint is exceeded, the server returns a 429 status code and prevents execution. Your code must be able to handle this type of error. For example, upon receiving a 429 error, wait up to one hour before retrying or reduce request volume to remain within rate limits. See also Rate limits.

Response (v1, legacy)

Version 1 is the default. The following sections provide details about error responses for version 1, including response format and error messaging.

TIP: For general information about offline measurement, FAQs, and other details, see Offline conversion events.

Success response object properties

The following table lists the POST /providerapi/offlineconversion object properties for a successful response.

FailedLine object properties (v1)

The following table lists the FailedLine object properties.

Failed response error codes and messages (v1)

The following table provides a list of common errors and their respective HTTP error codes.