Inbound Field-Aliasing
How Tugus normalizes incoming event data with different field names to the canonical schema.
Different senders (GA4, Meta Pixel, WooCommerce, Shopify, Klaviyo) use different
field names for the same thing. Tugus's normalization layer maps a set of
alternative names inside the data object to the canonical schema before
storage. Canonical keys always take precedence when both are set.
Scope. The direct /collect endpoint and the REST API validate against the
canonical schema and pass through only
known keys — unknown data.* fields (including most aliases) are dropped
before normalization. On these endpoints, send canonical keys; the one
alias that survives is items ↔ contents. The full alias map below applies
to the loose ingestion path (the server-side GTM bridge). When in doubt, send
canonical.
Field aliases (inside data)
| Canonical | Accepted aliases |
|---|---|
| content_id | product_id, item_id, sku, ProductID |
| content_ids | product_ids, item_ids |
| content_name | product_name, item_name, title, ProductName, name |
| content_type | item_type, product_type |
| content_category | item_category, product_category, category |
| brand | item_brand, product_brand, manufacturer, Brand |
| value | amount, revenue, total, subtotal, price |
| currency | currency_code, iso_currency, Currency |
| order_id | transaction_id, order_number, invoice_number, OrderId |
| contents | items, line_items, products, cart_items, Items |
| search_string | search_term, query, q, SearchTerm, search_query |
| shipping | shipping_cost, shipping_amount, Shipping |
| tax | tax_amount, Tax |
| coupon | coupon_code, discount_code, voucher, DiscountCode |
| payment_type | payment_method, pay_method |
| shipping_tier | shipping_method, delivery_method |
| link_url | href, url, outbound_url |
Item-level aliases (inside contents[])
| Canonical | Accepted aliases |
|---|---|
| id | product_id, item_id, sku, content_id, ProductID |
| name | product_name, item_name, title, ProductName |
| price | item_price, unit_price, amount, ItemPrice |
| quantity | qty, Quantity, count, num |
| category | item_category, product_category, Categories |
| brand | item_brand, product_brand, Brand, manufacturer |
| variant | item_variant, variant_title, sku_variant |
Example — WooCommerce style, normalized automatically
Incoming event on the loose ingestion path — note the fields sit inside data:
{
"event": "purchase",
"data": {
"product_id": "12345",
"product_name": "Sneaker X Pro",
"total": 179.80,
"currency_code": "eur",
"transaction_id": "ORD-001",
"line_items": [
{ "product_id": "A", "qty": 2, "item_price": 89.90 }
]
}
}After normalization, the stored data is:
{
"content_id": "12345",
"content_name": "Sneaker X Pro",
"value": 179.80,
"currency": "EUR",
"order_id": "ORD-001",
"num_items": 2,
"contents": [
{ "id": "A", "quantity": 2, "price": 89.90 }
]
}Idempotent: If your sender already uses the canonical schema, normalization changes nothing. Canonical fields always win — you can send both in parallel without conflicts.