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` … REQUIRED	`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` REQUIRED	`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` … RECOMMENDED	`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` … RECOMMENDED	`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_alias`	`string` (if reported via JSON, can be an array of strings)	This field adds additional globally-unique identifiers to an order so that data can be deduplicated. When an alias is added to an order, any future updates with a matching `order_id` or `order_alias` will get merged into the previous entry, allowing you to update orders over time. Read Order Status Reporting for more details.
`order_count`	`integer\|string`	The number of orders placed by this customer over all time. If not provided, this value will be inferred by Katalys by counting the number of times the `email_address` appears in your data silo. This value is used to determine if a customer is “new to file”: a 0-or-1 means the customer is new, a 2-or-higher means the customer is returning.
`order_id` REQUIRED	`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 the fulfillment status of the order. Some statuses have special meaning. We support values like `pending`, `paid`, `refunded`, and `rejected` (see below for more). Read 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` REQUIRED	`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` REQUIRED	`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` RECOMMENDED	`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.

Additional / Deprecated fields

These fields are no longer used, or have very limited use.

shipping_city: The name of the city where the product was shipped.
shipping_state: The name of the state or province where the product was shipped.
shipping_postal: The zip or postal code of the address where the product was shipped.
shipping_country: The country name where the product was shipped.
line_item_1_var: The variation ID or sub-ID of the actual product that was purchased.
line_item_1_qty: The quantity of this line item that was purchased.

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.

Acceptable Order Statuses

This table describes how we map the status you report into a status that we store and report on.

Sent Value	Recorded As	Meaning
`cancel`	`cancelled`	Order was cancelled before fulfillment.
`cancelled`	`cancelled`	Order was cancelled before fulfillment.
`shipped`	`fulfilled`	Order was paid and fulfilled.
`fulfilled`	`fulfilled`	Order was paid and fulfilled.
`closed`	`fulfilled`	Order was paid and fulfilled.
`completed`	`fulfilled`	Order was paid and fulfilled.
`approved`	`fulfilled`	Order was paid and fulfilled.
`paid`	`paid`	Order was paid.
`incomplete`	`pending`	Order is pending.
`manual verification required`	`pending`	Order is pending.
`pending`	`pending`	Order is pending.
`refunded`	`refunded`	Order was refunded.
`reversed`	`refunded`	Order was refunded.
`partial`	`partial_refund`	Order was partially refunded (not handled).
`reject`	`rejected`	Order was rejected as fraudulent before fulfillment.
`rejected`	`rejected`	Order was rejected as fraudulent before fulfillment.

Example Implementations

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