Merchant event data examples
This page provides examples to illustrate the POST /providerapi/offlineconversion request syntax and help you understand how to form valid conversion requests for uploading merchant product catalog events. For example, you can see how to include one or more user IDs per object in the Items array, along with additional event metadata required for merchant data, such as MerchantId, EventName, OrderId, and LineItems.
Here's what you need to know about these examples and additional resources:
- These examples are for demonstration purposes only and may not reflect production-ready data.
- For details on merchant product catalogs and product lists, see Commerce Solutions API.
IMPORTANT: For full upload requirements, property descriptions, accepted user ID formats, and syntax rules, see POST /providerapi/offlineconversion.
Single user ID per object
This example shows how to structure a POST /providerapi/offlineconversion request when uploading merchant conversion data with a single user ID per object. Each event item includes product-level details in the LineItems array, along with merchant-specific fields like MerchantId and OrderId.
{
"DataProviderId": "XYZdataprovider",
"Items": [
{
"UID2": "48MjlfIUZpOKNAm9nod7/jCLAXUYsnE1tpVHQSDS0uo=",
"TrackingTagId": "kqmtx93",
"TimestampUtc": "2025-03-19T10:06:55",
"ReferrerUrl": "https://www.example.com/",
"ClientIPAddress": "198.51.100.7",
"MerchantId": "12345",
"EventName": "purchase",
"Value": 1778.7,
"ValueCurrency": "USD",
"Country": "United States",
"Region": "OH",
"PostalCode": "44114",
"OrderId": "12073947167669368160",
"LineItems": [
{
"item_code":"017817838320",
"name":"Bose QuietComfort Earbuds",
"qty":1,
"price":279.00,
"cat":"Earbuds",
"item_brand": "Bose"
},
{
"item_code":"889842640724",
"name":"Microsoft Xbox Series X",
"qty":3,
"price":499.99,
"cat":"Gaming Consoles",
"item_brand": "Xbox"
}
],
"TD1": "Spring Promo",
"TD2": "Other optional custom content"
},
{
"RampID": "Xi3157bibbtjRnx4yby9Ko1rXW_FtYPYugQ2z2cB5oxNRTTlhI7gdZhvHzAkimEAkjB9Jj",
"TrackingTagId": "kqmtx93",
"TimestampUtc": "2025-03-19T10:06:55",
"MerchantId": "12345",
"EventName": "purchase",
"Value": 749.99,
"ValueCurrency": "USD",
"Country": "United States",
"Region": "OH",
"PostalCode": "44114",
"OrderId": "12073947167669368160",
"LineItems": [
{
"item_code":"887276717524",
"name":"Samsung Galaxy S23",
"qty":1,
"price":749.99,
"cat":"Smartphones",
"item_brand": "Samsung"
}
]
}
]
}
Multiple user IDs per object
The following sections provide examples that show how to pass multiple types of user IDs per object in the Items array of a POST /providerapi/offlineconversion request and also include merchant-specific metadata and product-level details.
Example 1: Using the user ID array
This POST /providerapi/offlineconversion request body example shows how to use the UserIdArray property to submit multiple user IDs in a structured array format, where each entry includes an ID type and its corresponding value. The format is controlled by the UserIdArrayMetadataFormat field, which defines the meaning of each position in the array. This structure provides a flexible and scalable method to associate multiple identity signals—including multiple IDs of the same type (as demonstrated by the two TDIDs in the array)—with each conversion event. For a mixed format alternative, see Example 3.
{
"DataProviderId": "XYZdataprovider",
"UserIdArrayMetadataFormat": ["type", "id"],
"Items": [
{
"MerchantId": "12345",
"TrackingTagId": "bnvcu47",
"UserIdArray": [
[0, "230a9666-996c-4c26-918e-eb2178a1f8fa"], //TDID
[0, "df2df528-e032-4851-b7c6-99287c7d6bce"], //TDID
[1, "af867d6a-1a08-5cd3-8fe7-3f0cdd6ac741"], //DAID
[6, "Xi3157bibbtjRnx4yby9Ko1rXW_FtYPYugQ2z2cB5oxNRTTlhI7gdZhvHzAkimEAkjB9Jj"] //RampId
],
"TimestampUtc": "2025-03-19T10:06:55",
"EventName": "purchase",
"Value": 7207.90,
"ValueCurrency": "USD",
"Country": "United States",
"Region": "OH",
"OrderId": "12073947167669368160",
"LineItems": [
{
"item_code":"885609031200",
"name":"Dyson V15 Detect",
"qty":2,
"price":699.99,
"cat":"Vacuum Cleaners",
"item_brand": "Dyson"
},
{
"item_code":"017817838320",
"name":"Bose QuietComfort Earbuds",
"qty":2,
"price":279.00,
"cat":"Earbuds",
"item_brand": "Bose"
},
{
"item_code":"889842640724",
"name":"Microsoft Xbox Series X",
"qty":3,
"price":499.99,
"cat":"Gaming Consoles",
"item_brand": "Xvox"
},
{
"item_code":"887276717524",
"name":"Samsung Galaxy S23",
"qty":5,
"price":749.99,
"cat":"Smartphones",
"item_brand": "Samsung"
}
],
"TD1": "Spring Promo",
"TD2": "More optional custom content"
},
{
"MerchantId": "67890",
"TrackingTagId": "jlsdk65",
"UserIdArray": [
[0, "9bfb80bf-995c-4215-9dc5-f3c82fcbda6a"], //TDID
[1, "a934b283-a381-4a0d-8a18-0368f9b19170"], //DAID
[2, "WjmpsHwlrRQSGt8Zt73+z/W83nZ0L659IWNmuBb7cDk="] //UID2
],
"TimestampUtc": "2025-03-19T09:58:55",
"EventName": "purchase",
"Value": 587.00,
"ValueCurrency": "USD",
"Country": "United States",
"Region": "NH",
"OrderId": "22345678920123456789",
"LineItems":
[
{
"item_code": "746775359539",
"price": 329.00,
"qty": 1
},
{
"item_code": "085955105062",
"price": 79.00,
"qty": 1
},
{
"item_code": "085955105062",
"price": 179.99,
"qty": 1
}
]
}
]
}
Example 2: Using individual IDs
This POST /providerapi/offlineconversion request body example demonstrates how to pass multiple user IDs by including them as individual fields directly within each object in the Items array. Instead of using the UserIdArray format, each ID type appears as a top-level property inside the event object. This approach can be easier to read and validate when each object includes only a few user IDs or when working with a fixed and known set of supported ID types, especially if the IDs are of different types. For example, this option works for the second item shown in Example 1 but not for the first item, which has two TDIDs.
{
"DataProviderId": "XYZdataprovider",
"Items": [
{
"MerchantId": "67890",
"TrackingTagId": "jlsdk65",
"TimestampUtc": "2025-03-19T09:58:55",
"TDID": "9bfb80bf-995c-4215-9dc5-f3c82fcbda6a",
"DAID": "a934b283-a381-4a0d-8a18-0368f9b19170",
"UID2": "WjmpsHwlrRQSGt8Zt73+z/W83nZ0L659IWNmuBb7cDk=",
"EventName": "purchase",
"Value": 587.00,
"ValueCurrency": "USD",
"Country": "United States",
"Region": "NH",
"OrderId": "22345678920123456789",
"LineItems": [
{
"item_code": "746775359539",
"price": 329.00,
"qty": 1
},
{
"item_code": "085955105062",
"price": 79.00,
"qty": 1
},
{
"item_code": "085955105062",
"price": 179.99,
"qty": 1
}
]
}
]
}
Example 3: Mixed formats
This POST /providerapi/offlineconversion request body example illustrates how to mix the UserIdArray format and individual ID fields across different event objects within the same request. Some objects use the array-based structure for flexibility, while others list IDs explicitly using individual fields. This hybrid approach can be useful when your data ingestion pipeline supports multiple formats or when integrating events from different sources with varying identity schemas. For example, this option is an alternative for the items shown in Example 1 where the first item has two TDIDs, while the second item has three user IDs of different types.
{
"DataProviderId": "XYZdataprovider",
"UserIdArrayMetadataFormat": ["type", "id"],
"Items": [
{
"MerchantId": "12345",
"TrackingTagId": "bnvcu47",
"UserIdArray": [
[0, "230a9666-996c-4c26-918e-eb2178a1f8fa"], //TDID
[0, "df2df528-e032-4851-b7c6-99287c7d6bce"], //TDID
[1, "af867d6a-1a08-5cd3-8fe7-3f0cdd6ac741"], //DAID
[6, "Xi3157bibbtjRnx4yby9Ko1rXW_FtYPYugQ2z2cB5oxNRTTlhI7gdZhvHzAkimEAkjB9Jj"] //RampId
],
"TimestampUtc": "2025-03-19T10:06:55",
"EventName": "purchase",
"Value": 7207.90,
"ValueCurrency": "USD",
"Country": "United States",
"Region": "OH",
"OrderId": "12073947167669368160",
"LineItems": [
{
"item_code":"885609031200",
"name":"Dyson V15 Detect",
"qty":2,
"price":699.99,
"cat":"Vacuum Cleaners"
},
{
"item_code":"017817838320",
"name":"Bose QuietComfort Earbuds",
"qty":2,
"price":279.00,
"cat":"Earbuds"
},
{
"item_code":"889842640724",
"name":"Microsoft Xbox Series X",
"qty":3,
"price":499.99,
"cat":"Gaming Consoles"
},
{
"item_code":"887276717524",
"name":"Samsung Galaxy S23",
"qty":5,
"price":749.99,
"cat":"Smartphones"
}
],
"TD1": "Spring Promo",
"TD2": "More optional custom content"
},
{
"MerchantId": "67890",
"TrackingTagId": "jlsdk65",
"TimestampUtc": "2025-03-19T09:58:55",
"TDID": "9bfb80bf-995c-4215-9dc5-f3c82fcbda6a",
"DAID": "a934b283-a381-4a0d-8a18-0368f9b19170",
"UID2": "WjmpsHwlrRQSGt8Zt73+z/W83nZ0L659IWNmuBb7cDk=",
"EventName": "purchase",
"Value": 587.00,
"ValueCurrency": "USD",
"Country": "United States",
"Region": "NH",
"OrderId": "22345678920123456789",
"LineItems": [
{
"item_code": "746775359539",
"price": 329.00,
"qty": 1
},
{
"item_code": "085955105062",
"price": 79.00,
"qty": 1
},
{
"item_code": "085955105062",
"price": 179.99,
"qty": 1
}
]
}
]
}