Order Status Reporting

This page is Part 3 in a 3-part series on how to develop a custom integration with Katalys.

After implementing the JavaScript tracking on the frontend of your website, you can augment this information by providing server-to-server status updates on reported orders. This page describes use cases and fields available for server-to-server data collection.

Use Cases

The follow use cases can be enabled through Order Status Reporting.

Add additional information to the order.
Sometimes you only know the Order ID (the bare minimum) on the Thank-You page. You can add additional information to the order via your backend. Most commonly, integrations post Line Item and Discount information fields separately.
Support multi-stage fulfillment.
If configured correctly on your Offer, you can define order_status: "pending" within your frontend implementation, then update order_status to "paid" later via a server-to-server ping.
Automatic refunds.
If configured correctly on your Offer, and if reported within a fast time window, you can report order_status: "refunded" or order_status: "cancelled" to ensure the order cannot be attributed to a Katalys Affiliate. This is most-commonly used by Advertisers with specific asynchronous fraud-detection methodologies.
Track and filter existing customers.
If configured correctly on your Offer, you can set order_count: to the be the total number of orders placed by the current customer. When this value is greater than 1, the customer is considered a “returning customer” and can match existing Triggers available with KMP.
Cross-correlate orders between systems.
Sometimes the Order ID available within JavaScript must be correlated to another system. This is accomplished by reporting order_alias: "{VALUE}". Warning: this will merge orders, and might change the Order ID used for the order. This is most-commonly used when a recurring order system is different from your normal CRM, and you want to ensure the orders are attributed only once.

Basics

To submit an update, you must execute a POST request with a valid JSON payload to the URL https://db.revoffers.com/v2/_tr_offline. You should expect to receive an HTTP 204 response code if the data was received.

To correlate the submitted data with previously-received data, you must provide the following fields:

site_id This is the “script name” of your tracking snippet. If your script is /js/abcdefg.com.js, then your Site ID value is abcdefg.com.
order_id This is the exact value provided on the Thank-You page.

PHP Example

PHP

const KATALYS_SITE_ID = "abcd.com";

function updateKatalysOrder($orderId, array $data) {
  $data['site_id'] = KATALYS_SITE_ID;
  $data['order_id'] = $orderId;
  $ch = curl_init("https://db.revoffers.com/v2/_tr_offline");
  curl_setopt_array([
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode($data)
    CURLOPT_HTTPHEADER => [ "Content-Type: application/json" ],
  ]);
  curl_exec($ch);
  curl_close($ch);
}

// example usage:
updateKatalysOrder($myOrderId, [ "order_status" => "paid" ]);

TypeScript Example

TYPESCRIPT

const KATALYS_SITE_ID = "abcd.com";

function updateKatalysOrder(orderId: string, updates: Record<string, string>): Promise<void> {
  updates.site_id = KATALYS_SITE_ID;
  updates.order_id = orderId;
  return fetch("https://db.revoffers.com/v2/_tr_offline", {
    headers: { "content-type": "application/json" }
  }).then(res => {
    console.debug("data sent")
  })
}

// example usage:
updateKatalysOrder(myOrderId, { order_status: "paid" });

Validating Your Integration

All data received from the frontend or backend of your website is processed in the order you submit it. It is typically updated within 30 seconds or less. To confirm your integration, you will need to submit an order to our system and then load the Katalys Marketing Platform entry for your order.

Load Katalys Marketing Platform or go here.
Navigate to Reports → Conversions
Find the Order by clicking “Filters” and filtering for your Order ID
Click on the “Details” icon in the far-left column. Review the details on this screen to ensure they match the data you reported to our system.
- If you see something that looks wrong, contact Katalys Support.

Available Fields

The following fields are available to set in server-to-server implementations, or via a JavaScript snippet on your Thank-You page.

Required Fields

order_id: {string} example: “12345”
We use this field to disambiguate orders placed by your customers. It is important that this value be globally unique for your e-commerce account!
sale_amount: {float|string} example: 25.67
This should be a numeric value without currency.
subtotal_amount: {float|string} example: 24.95
This is sale_amount minus shipping and tax.
email_address: {string} example: “email@example.com”
We use this field to disambiguate customers. Without this field, we cannot perform any special logic like double-conversion avoidance or customer-exclusion.
Discount fields:
For each applied discount or coupon, include the fields discount_X_code and discount_X_amount.
- discount_1_code: {string} example: “REVOFFERS_EXAMPLE”
- discount_1_amount: {float|string} example: “1.50”
- discount_2_code:
- discount_2_amount:
- … etc.

Required, but has defaults:

order_time: {string} example: “2018-01-01 01:23:40-08:00” default: use current time
This is the time the order was first placed. We prefer orders to be reported immediately after they happen. However, if the tracking code is running more than 5 minutes after the order was placed, then this field is required so we don’t double-count orders.
currency: {string} example: “EUR” default: “USD”
We default to USD. This is required for international orders.
user_agent: {string} default: navigator.user_agent
If you’re including _track.js on the user’s browser session, then this field is tracked automatically! No action needed.
ip_address: {string} default: http_remote_addr
If you’re including _track.js on the user’s browser session, then this field is tracked automatically! No action needed.
site_id: {string} default: http_host header
If you use a custom site_id field in your Visitor Reporting tracking code, then you must include the same value here also.

Optional Fields

shipping_amount: {string} example: “4.99”
When subtotal is not available, shipping_amount and tax_amount are required. Must be in the same currency as total_amount.
tax_amount: {string} example: “1.48”
When subtotal is not available, shipping_amount and tax_amount are required. Must be in the same currency as total_amount.
Line Item fields
For each line item of the order, include the fields lineitem_X_title, lineitem_X_sku, lineitem_X_price.
- line_item_1_title: {string} example: “Wellness Bundle #4”
- line_item_1_sku: {string} example: “WLNS_BUNDLE_$”
- line_item_1_price: {float|string} example: “1.99”

Line Item fields are required if you intend to implement product-specific (SKU-based) payouts for your affiliates. These fields must either be implemented in your Thank-You page implementation, or via a Server-to-Server implementation (see Part 3 below).

Additional Fields

shipping_city
shipping_state
shipping_postal
shipping_country
line_item_X_var
line_item_X_qty