Reporting Schema

This page defines the valid key-value pairs that Katalys uses for attribution and reporting. These values can be reported by any of the following methods:

reported via the JavaScript SDK with _revoffers_track.push({ … })
sent via POST request with a valid JSON payload to https://db.revoffers.com/v2/_tr_offline.

Available Keys

This table defines all available keys accepted by the Katalys Tracking SDK. All values must be non-empty string or number values. Any other values, such as objects, will be ignored. This means you must flatten any objects in the structure using the appropriate keys as defined below. For examples, see Thank-You Page Tracking or Order Status Reporting.

Key	Format	Note
`action_type`	`string`	This is the type of the conversion registered by the advertiser, typically used to control payout values. Examples might be `lead`, `online sale`, or `form submit`. Values will be dependent on the advertiser’s integration with Katalys. The values `action` (user-behavioral field) and `action_type` (order metadata field) are both registered as events, and are similar. Read more about these differences.
`currency`	`string` (default `USD`) Example: `EUR`	When defined and the value is not `USD`, we attempt to convert all sales values (`sale_amount`, `subtotal_amount`, `line_item_X_price`, etc.) from this defined currency into USD. Our billables are always defined in USD, so this is required for orders fulfilled in non-USD currencies.
`discount_1_amount` `discount_2_amount` …	`float\|string` Example: `1.50`	The value of the discount, promo, or coupon. This value is used for reporting in the Katalys portal. For each applied discount or coupon, define the key `discount_X_amount`, starting at 1. Read more about multi-key fields.
`discount_1_code` `discount_2_code` …	`string` Example: `KATALYS_INFLUENCER`	Required. The discount code, promo code, or coupon code used for this order. For each applied discount or coupon, define the key `discount_X_code`, starting at 1. Read more about multi-key fields.
`email_address`	`string` Example: `email@example.com`	Required. We use this field to disambiguate customers. This value can be any string, but it must match the previously-reported string for this customer (case-insensitive match). Without this field, we cannot perform any special logic like double-conversion avoidance or customer-exclusion.
`client_ip`	`string` Default: `http_remote_addr`	The IP address of the user who completed the purchase. Required only when reporting server-to-server events, such as off-site clicks or conversions that are not reported via the JavaScript SDK.
`line_item_1_price` `line_item_2_price` …	`float\|string` Example: `1.99`	The price of a line item as a numeric value without currency. For each line item, define the key `line_item_X_price`, starting at 1. Read more about multi-key fields.
`line_item_1_sku` `line_item_2_sku` …	`string` Example: `WLNS_BUNDLE_4`	Recommended. The SKU of a line item. For each purchased item, define the key `line_item_X_sku`, starting at 1. Read more about multi-key fields. Line Item fields are required if you intend to implement product-specific (SKU-based) payouts for your affiliates.
`line_item_1_title` `line_item_2_title` …	`string` Example: `Wellness Bundle #4`	Recommended. The title of a line item. For each purchased item, define the key `line_item_X_title`, starting at 1. Read more about multi-key fields. Line Item fields are required if you intend to implement product-specific payouts for your affiliates.
`order_id`	`string` Example: `12345`	Required. Non-empty string value at least 3 or more characters long. We use this field to disambiguate orders placed by your customers. It is important that this value be globally unique within your Tracking ID. If you have staging/development data with the same Order IDs as production, you must create a second Tracking ID for your testing data. See How Tracking IDs Work for more information.
`order_status`	`string` Example: `shipped`	This is a flag indicating the fulfillment status of the order. Some statuses have special meaning. Some of the values we support are `pending`, `paid`, `refunded`, and `rejected`. See Order Status Reporting for how to update this field after the order is created.
`order_time`	`string` in ISO 8601 compatible format Example: `2018-01-01 01:23:40-08:00`	This is the time the order was placed. Orders should be reported immediately after they happen, but certain cases require delayed reporting to update order status. For delayed reporting or subsequent order updates, this field is required so we don’t double-count orders. See Order Status Reporting for more details.
`order_value`	`float\|string` Example: `5.67`	(derived value) This is the value of the order minus tax, minus shipping/handling, minus discounts. This number is validated against any given values for `sale_amount`, `subtotal_amount` , `shipping_amount`, and/or `tax_amount` to ensure accuracy. This value is used when calculating CPS (cost per sale) payouts. This key can be defined explicitly, but we recommend defining `sale_amount`, `subtotal_amount`, `shipping_amount` and `tax_amount` instead for the highest accuracy.
`sale_amount`	`float\|string` Example: `25.67`	Required. This should be a numeric value without currency.
`shipping_amount`	`string` Example: `4.99`	Used to calculate `order_value`. When subtotal is not available, `shipping_amount` and `tax_amount` are required. Must be in the same currency as `sale_amount`.
`site_id`	`string` Example: `KA-1234567890`	Required. This is the Tracking ID associated with your account. It is defined by default when including your JavaScript tracking code, but must be provided manually when reporting server-to-server data. Use one Tracking ID across all web properties for an environment. If you have a staging/development environment, create a second Tracking ID for your testing data. See How Tracking IDs Work for more information.
`subtotal_amount`	`float\|string` Example: `24.95`	Recommended. This is sale_amount minus shipping and tax, defined as a numeric value without currency. Used to calculate `order_value`.
`tax_amount`	`string` Example: `1.48`	Used to calculate `order_value`. When subtotal is not available, `shipping_amount` and `tax_amount` are required. Must be in the same currency as `sale_amount`.
`user_agent`	`string` Default: `navigator.user_agent`	The user-agent string of the browser the user used to complete the purchase (Mozilla Reference). Required only when reporting server-to-server events, such as off-site clicks or conversions that are not reported via the JavaScript SDK.

Sending Arrays As Multiple Keys

Certain keys such as line_item_* and discount_* are numbered to keep the sent object flat. This means you must define keys such as line_item_1_sku and line_item_2_sku instead of passing an array of into these keys.

The SDK accepts keys that start at 0 (i.e. line_item_0_sku) or 1 (i.e. line_item_1_sku), but we recommend starting from 1 for easy reading.
You must number your keys in numeric sequence. Do not have gaps between your sequence. For example, if you have 2 line items, define line_item_1_sku and line_item_2_sku instead of using line_item_4_sku and line_item_7_sku.

Example Implementations

For examples and more guidance on using these keys, read Thank-You Page Tracking or Order Status Reporting.