Webgains Server To Server (Conversion API) Tracking Guidance

Introduction

Server-to-Server (S2S) tracking is a robust method for managing attribution and recording transactions. It involves using a server callback initiated by the advertiser and directed to a designated API endpoint provided by Webgains.

There are three core routes that Webgains provides to allow you to get S2S integrated as quickly and simply as possible.

Stape.io

To simplify your S2S integration, head over to http://stape.io and register for an account. Following the steps provided using the Webgains sGTM templates. https://stape.io/solutions/webgains-tag-for-server-to-server-conversion-tracking Webgains S2S tag.

Google Tag Manager (sGTM)

We support server-side Google Tag Manager (sGTM) with a ready-to-use tag template available on request. Simply create a Google Cloud account and set up sGTM to work with your site https://developers.google.com/tag-platform/tag-manager/server-side , then request our sGTM templates, and we can easily support you getting S2S up and running directly via Google Cloud.

Client Managed integration

This guide outlines how to manually integrate S2S tracking for your site or store by capturing the click_id as an HTTP-only cookie and sending conversion data either via JSON POST or GET requests.

Capturing the Click ID and Setting an HTTP-only Cookie

1. Capture the Click ID and Set the HTTP-only Cookie

To ensure the click_id is securely stored, set it as an HTTP-only cookie on your server. There are other methods for storing the click_id; however, this is what we recommend. By default, the click_id is stored in the wgu URL parameter.

2. Retrieve the Click ID from the HTTP-only Cookie

In your server-side code, retrieve the click_id from the HTTP-only cookie and include it in your S2S conversion request.

S2S Conversion Request Methods

JSON POST Request

• Endpoint: https://api.webgains.io/queue-conversion

• Method: POST

• Headers: Set Content-Type to application/json.

• Payload: JSON object with conversion details.

Example POST Payload:

Order Data

{
  "ids": [
    {
      "name": "s2s",
      "value": "117_1633304_16651550532817_3f4e40a2a3"
    }
  ],
  "value": "97.50",
  "currency": "GBP",
  "orderReference": "ORD123456789",
  "comment": "Test transaction",
  "items": [
    {
      "price": "60.00",
      "name": "T-Shirt",
      "code": "TSHIRT001",
      "voucher": ""
    },
    {
      "price": "37.50",
      "name": "Jeans",
      "code": "JEANS002",
      "voucher": ""
    }
  ],
  "customerId": "CUSTOMER123",
  "voucherId": "DISCOUNT10",
  "location": "https://example.com/checkout",
  "programId": "312042",
  "customerType": "new"
}

Example GET Request:
Order Data

URL Format:

https://api.webgains.io/queue-conversion?ids[0][name]={name}&ids[0][value]={click_id}&value={transaction_value}&currency={currency}&eventId={event_id}&orderReference={order_reference}&comment={comment}&items[0][event]={item_event}&items[0][price]={item_price}&items[0][name]={item_name}&items[0][code]={item_code}&items[0][voucher]={item_voucher}&items[1][event]={item_event}&items[1][price]={item_price}&items[1][name]={item_name}&items[1][code]={item_code}&items[1][voucher]={item_voucher}&customerId={customer_id}&voucherId={voucher_id}&location={checkout_url}&programId={program_id}&customerType=[customer_type]

Building the Query String

Each key/value pair is turned into a URL-encoded component. Notice that arrays are represented using bracket notation.

Breakdown:

• Base URL:

  CODE

  https://api.webgains.io/queue-conversion?

• IDs Array:
  Two properties for the first element in the ids array:

  CODE

  ids[0][name]=s2s&
  ids[0][value]=117_1633304_16651550532817_3f4e40a2a3&

• Transaction Details:

  CODE

  value=97.50&
  currency=GBP&
  orderReference=ORD123456789&
  comment=Test%20transaction&

  Note: The space in "Test transaction" becomes %20.

• Items Array:
  For the first item (index 0):

  CODE

  items[0][price]=60.00&
  items[0][name]=T-Shirt&
  items[0][code]=TSHIRT001&
  items[0][voucher]=&

  For the second item (index 1):

  CODE

  items[1][price]=37.50&
  items[1][name]=Jeans&
  items[1][code]=JEANS002&
  items[1][voucher]=&

• Additional Fields:

  CODE

  customerId=CUSTOMER123&
  voucherId=DISCOUNT10&
  location=https%3A%2F%2Fexample.com%2Fcheckout&
  programId=312042&
  customerType=new

Final GET Request URL

Concatenating all these parts together gives you the final URL:

https://api.webgains.io/queue-conversion?ids[0][name]=s2s&ids[0][value]=117_1633304_16651550532817_3f4e40a2a3&value=97.50&currency=GBP&orderReference=ORD123456789&comment=Test%20transaction&items[0][price]=60.00&items[0][name]=T-Shirt&items[0][code]=TSHIRT001&items[0][voucher]=&items[1][price]=37.50&items[1][name]=Jeans&items[1][code]=JEANS002&items[1][voucher]=&customerId=CUSTOMER123&voucherId=DISCOUNT10&location=https%3A%2F%2Fexample.com%2Fcheckout&programId=312042&customerType=new

Payload Structure and Field Descriptions

Payload Structure and Field Descriptions

Here’s how to structure your JSON payload and what each field represents:

E-commerce Order Data Used in Examples

Order Details:

Order Number: ORD123456789

Items Ordered:

1. T-Shirt

   • SKU: TSHIRT001

   • Price (Each): £40.00

   • Price After Discount: £36.00

   • Quantity: 2

   • Price Excluding VAT (Each): £30.00

   • Total Price Excluding VAT: £60.00

   • VAT (Each): £6

   • Total VAT for T-Shirts: £12

2. Jeans

   • SKU: JEANS002

   • Price: £50.00

   • Price After Discount: £45.00

   • Quantity: 1

   • Price Excluding VAT: £37.50

   • Total Price Excluding VAT: £37.50

   • VAT: £7.50

Order Summary:

• Subtotal (Before Discount): £130.00

• Discount (10%): -£13

• Subtotal After Discount: £117.00

• Shipping Cost: £5.00

• Total: £123

• Total VAT: £19.5

• Expected tracking Order Value: £97.50

Notes on Conversion Customization

• Items with Voucher Discounts: If voucher codes have been used that are specific to one item, ensure the discount is reflected in the items array. Subtract the discount proportionally from the item.

• Orders with Voucher Discounts: If a voucher code for a discount on the whole order has been used, please ensure this is subtracted correctly from all values provided.

• Total Amount Matching: Ensure that the total amount from the items array matches the value field to ensure accurate commission calculations.

• VAT: If you are not paying commission on VAT, please ensure the prices provided are minus VAT

• Shipping: If you are paying commission on shipping, please ensure this is added to the value of the order, you will also need to add this as an item in the item tracking.

  • Example:

    CODE

                {
                    "price": "4.99",  // Item price excluding VAT
                    "name": "Shipping",
                    "code": "NEXTDAY",
                    "voucher": ""
                },

• Item Quantity: We do not capture the quantity of items, please ensure the value for each item is the price of the item multiplied by the quantity.