Tracking

Getting started

Important

Does the Referral receive a voucher? See voucher tracking.

Whenever a referral finalizes a sale on your website we’d like to be informed. This process, known as sales tracking, serves 3 purposes:

We need to identify the referral.
We need a way to connect that particular referral to the right promoter.
We need to communicate with both parties to pay out the reward.

Our sales tracking is based on callbacks: a signal from your system to ours to inform us the state of the sale has changed. We differentiate between two types of callbacks:

a. Sale confirmation
This first callback lets us know that the referred friend became a customer through your online sales funnel. This is needed to link the referral to the right promoter and inform all involved parties. We match the Referral to the promoter based on the mgmco_saleid. Each promoter has a unique referral link that will redirect the Referral to the start of your salesfunnel (also called Referral Landing Page). In that redirect our system creates a mgmco_saleid that is linked to the promoter (referral link). When the Referral successfully becomes a customer, the mgmco_saleid is sent back in the callback with all of the needed Referral information.

b. Sale validation
To make sure those referrals are actual customers and have not canceled or violated the terms of service, there needs to be a sale validation after the cancellation period (usually 14 days). The validation is meant to inform us whether the sale has been approved (completed) and can be paid out, or rejected (aborted).

You might have an existing system that does the validation and automate the callback for you (ask your developers!). If not, we have the CSV importer as a solution that lets you import a list with your approved and rejected sales. Ask our operations team for details about the process.

If you don’t have a cancellation period, you can skip this second validation and change the ‘state’ to completed right away.

More info on callbacks here

Implementation

What does your developer need to do?

We pass the mgmco_saleid to your platform via a param in the URL
Your frontend needs to store this MGMCo sale ID as a cookie with a lifetime of 30 days (How?)
When the Referral completes your sales funnel, trigger a callback by passing the Referral information and the mgmco_saleid to the MGMcoBuyerInfo object in our Ping.js script.
Your frontend can pass the MGMCo sale ID to your API so it can be stored with the sale (optional; see Sale validation).
Your API can make a second callback to complete the sale when it is ready for payout (optional; see Sale validation).

Ping.js script

Implementation Ping.js

We maintain a small, easy-to-use JavaScript file called ping.js that handles the tracking request. Include it on your sales funnel’s confirmation or thank-you page and send us the required Referral information.

Load the script on the correct page.
Fill the MGMcoBuyerInfo object with the correct payload.
Call the window.mgmcoPing.send(MGMcoBuyerInfo) function.

The callback must include the MGMCo sale ID and the Referral’s email address. Include their name, bank account and any other fields required for your campaign setup.

Example

<script src="https://tracking.membergetmember.co/scripts/ping.js"></script>
<script>
  (function() {
    var MGMcoBuyerInfo = {
     // Required
      email: 'client@email.com',

     // Include when required for your campaign setup
      name: 'Name of your new client',
      bank_account: 'Bank account of your new client',

     // for Starter and Pro pricing plan only: total order value on which we'll base our commission
      amount: 'total order amount',

     // One of the following is required, not both
      sale_id: 'MGMco sale id',
      cookie_name: 'Name of your cookie with the MGMco sale id',

     // Set the sale state
      state: 'confirmed',

    // Insert other parameters if needed
      customer_id: 'Customer ID of your new client', // Handy for failed sale matches
      order_id: 'Order ID of the new order' // Handy for failed sale matches
    };
    window.mgmcoPing.send(MGMcoBuyerInfo);
  })();
</script>

Verify the implementation

Walk through the complete referral flow on your website. Confirm that the MGMCo sale ID is stored under the configured cookie name, complete the sales funnel and inspect the browser’s Network panel on the thank-you page. You should see one request to https://api.membergetmember.co/sales/callback containing the expected Referral information. Also verify that the configured confirmation messages are sent.

Getting started

Important

Does the Referral receive cash, a manually handled reward or no reward? See sale ID tracking.

Whenever a referral finalizes a sale on your website we’d like to be informed. This process, known as sales tracking, serves 3 purposes:

We need to identify the referral.
We need a way to connect that particular referral to the right promoter.
We need to communicate with the participants about the referral and reward.

Sales tracking improves the customer experience and enables you to convert your newly referred customers into promoters as well, amplifying the reach of your campaign!

A voucher can be assigned only as the Referral’s reward. The Promoter reward can be cash, manually handled or no reward.

The Promoter shares their referral link with friends. After a Referral enters their name and email address in the Referral Landing Widget, they receive a unique voucher code and can continue to your sales funnel.

Implementation

Voucher reward tracking requires you to:

Support voucher redemption in your sales funnel.
Provide MGMCo with a set of Referral voucher codes. Codes can be supplied in an Excel file with one column, a text file with one code per line or a CSV file. MGMCo will import them into the campaign.
Implement the Referral Landing Widget. After the Referral submits their details, the widget assigns a unique voucher and redirects them to the configured sales funnel URL with the voucher code in the voucherCode query parameter.
Retain the voucher code through the sales funnel so it is available on the confirmation or thank-you page.
When the Referral redeems the voucher, send a callback using our Ping.js script.

For example: https://www.your-company.com/?voucherCode=XXXXX

Ping.js script

Implement the Ping.js script

Load the script on the correct page.
Fill the MGMcoBuyerInfo object with the correct payload.
Call the window.mgmcoPing.voucher(MGMcoBuyerInfo) function.

Trigger the script only for an MGMCo Referral sale and only once. Your implementation may need a condition to enforce this.

The callback must include the voucher code and the Referral’s email address. Their name is recommended.

Example

<script src="https://tracking.membergetmember.co/scripts/ping.js"></script>
<script>
  (function() {
  var MGMcoBuyerInfo = {
    email: 'your_client@email.com',
    voucher: 'voucher-code',
    name: 'Name of your new client',
  // total order value on which we'll base our commission
    amount: 'total order amount',
  // optional information you can later use for analysis
    order_id: 'your order_id'
  };
  window.mgmcoPing.voucher(MGMcoBuyerInfo);
})();
</script>

Verify the implementation

Walk through the complete voucher flow on your website. Register a Promoter, follow their share link, submit the Referral Landing Widget and confirm that the assigned voucher code reaches your sales funnel. Redeem the voucher, complete the funnel and inspect the browser’s Network panel on the thank-you page. You should see one request to https://api.membergetmember.co/vouchers/callback containing the voucher code and expected Referral information. Also verify that the configured confirmation messages are sent.

Tracking Overview

There are 2 occasions where you may have to make a callback to our API:

Upon checkout, when a sale confirms.
Upon validation, when a sale completes.

In order to know which sales are awaiting validation, there is also an in-between step: sales retrieval.

Here we will give a summary of all the possible steps needed to bring a sale from checkout to finalization.

A. Sale Confirmation

The first callback tells us that the sale has [confirmed](/tracking/#sales_trackinggetting_started). You have 2 options in making the first callback:

Load our tracking script on the sale confirmation (or thank you) page and call a function from the script with the required payload (described below). Read more…
Make a callback from your API to ours. Read more…

The choice is yours. With the first option you will not have to touch your API. With the 2nd option you may automate validation and save data from your MGM program along with the sale.

B. Sale Retrieval

There are several ways to find sales that need to be validated: 1. Sales can be exported manually from the MGmco database by using the sales-export tool in the Campaign Manager. [Read more...](/campaign-manager/#dashboardsalesexport) 2. Retrieve the sales from the MGMco database via the `sales-to-validate` endpoint from mgmco api. [Read more...](/tracking/#sales-to-validate) 3. Keep track of mgmco sales in your own data store, and retrieve them from there.

C. Sale Validation

The second callback tells us whether the sale has been completed or aborted. After this callback we inform the user that they will be paid (or why they won't be paid) and soon after we will transfer their reward.

Approve or reject sales individually in the Campaign Managers Sales table.
Validate the sales on your end, and produce a csv file that can be processed by the Campaign Managers sales-import tool. Read more…
Use the validate-sale endpoint on the mgmco api. Read more…

examples

The three steps above can be used in any combination. Here are some examples:

1. least dev work, but manual sales validation
A1 - B1 - C1

2. most dev work, but full automation
A2 - B2 - C3

API

This is an overview of the available api endpoints that you can use to automate the sales tracking.

Ask your onboarder for an api key. This key is needed for all api calls.

Confirm Sale

This endpoint can be called after a referral makes a purchase on your website. It is an alternative to implementing the ping script.

Sale ID

Property	Value
Method	`POST`
Hostname	`api.membergetmember.co`
Path	`/confirm-sale`
Headers	`Content-Type: application/json`
Body	See Payload

Voucher

Property	Value
Method	`POST`
Hostname	`api.membergetmember.co`
Path	`/confirm-sale/voucher`
Headers	`Content-Type: application/json`
Body	See Payload

Retrieve Sales

Use this endpoint to fetch all sales that were confirmed in a given time period, and not yet validated.

Property	Value
Method	`POST`
Hostname	`api.membergetmember.co`
Path	`/sales-to-validate`
Headers	`Content-Type: application/json`

Request body:

{
  "api_key": "API_KEY",
  "start": "START_DATE",
  "end": "END_DATE"
}

The expected date format is yyyy-mm-dd, e.g.: 2022-05-11

Validate Sale

For approving or rejecting a sale.

Property	Value
Method	`POST`
Hostname	`api.membergetmember.co`
Path	`/validate-sale`
Headers	`Content-Type: application/json`

Request body:

{
  "api_key": "API_KEY",
  "sale_id": "SALE_ID",
  "state": "STATE",
  "reason": "Rejection reason"
}

The state field can only be completed or aborted.

The reason field is required in case the sale is aborted.

Payload

The payload of a callback may look like this:

{
  "sale_id": "SALE_ID",
  "email": "EMAIL",
  "api_key": "API_KEY",
  "name": "NAME",
  "bank_account": "BANK_ACCOUNT",
  "source": "SOURCE",
  "state": "STATE",
  "other": "OTHER",
  "...": "..."
}

Use the table below as a reference for which parameters should be included in the callbacks.

Key	Value	Type	Description
`sale_id`	MGMco sale ID	(Required *)	A 24-character sale ID that you got from our system. This ID should be stored in your database. The ID is provided as a query parameter called `mgmco_saleid`. Read more…
`cookie_name`	Name of cookie that holds MGM sale ID	(Required *)	You may pass the `sale_id` directly, but if the `sale_id` is stored in a custom cookie and you use the ping script implementation, then you may pass the `cookie_name` parameter instead. The script will retrieve and post the stored sale ID.
`voucher`	MGMco voucher code	(Required **)	One of the voucher codes that you uploaded in the Campaign Manager.
`email`	Emailaddress buyer	Required	The emailaddress of the buyer. This is needed for communication and payout purposes.
`api_key`	API key	Required**	We’ll provide you with an API key. Without this key you won’t be able to update any sales.
`name`	Name buyer	Recommended	The name of the buyer. We will use this information to personalize communication.
`bank_account`	IBAN buyer	Recommended	The bankaccount of the buyer. This should be a valid IBAN. We will use this information to pay out the buyer reward once the sale completes. If you work with voucher rewards or pay out the reward yourself this is not needed.
`source`	Origin	Recommended	We use the following naming convention: `{{client_name}}backend{{language}}` (for example `anderzorg_backend_nodejs`). This information will help us in case troubleshooting is needed.
`state`	Sale state	Recommended	Accepts `confirmed`, `completed`, and `aborted`. If no state is provided, then the sale will confirm. It is recommended to provide a state to avoid misinterpretations.
`reason`	Reason for aborting	(Required)	In case of aborting a sale with a callback, you are required to provide a reason.
`other`	-	Optional	You may add any other relevant data. We will save this as metadata. Data like your own `sale ID` or `customer ID` has proven valuable for customer support employees and operational teams that perform sale validation.

* Only sale_id or cookie_name is required, not both. cookie_name is only relevant when using frontend tracking via our Ping.js script. Use these fields for sale ID tracking, not voucher tracking.

** only use voucher if you have a voucher reward. If so, do not use sale_id or cookie_name

*** api_key is only relevant when using back end API tracking.