Step 3: Tracking conversions

PartnerStack needs to know when a referred visitor to your landing page converts to a user.

The data that must be sent with this event is very minimal and documented the following code block.

URL: https://partnerlinks.io/conversion/xid

Method: POST

Content Type: application/json

{		
	// The click ID we stored in the previous section
	// Click ID is required
	// Click ID should be unique (if it's not that's ok PS will accept it)
	"xid": "69Fe7JSSXkDs" [REQUIRED], 
	// A unique identifier for the customer, this is the
	// ID you will use to reference the customer in our API
	// Customer key is required
	// Customer key has to be unique
	"customer_key": "test_customer" [REQUIRED],
	// Customer email and name, due to privacy concerns you may want to 
	// supply anonymized values here
	// Email is optional
	"email": "[email protected]",
	// Name is optional, though you may supply a non-unique value that is the
	// same for each customer (e.g. "ACME Customer")
	"name": "xxxxxxx yyyyyy",
	// If using Stripe, Chargebee, Recurly, Chargify webhook integration and the customer
	// record is created in the payment platform before the customer is created in PartnerStack, you can pass the customer ID from the payment processor in the 
	// provider_key field. 
	"provider_key": "cus_12345"
	// The origin of the signup
	"origin": "acme.com",
	// An IP address is a unique address that identifies a device on 
	// the internet or a local network of the customer
	"ip_address": "198.51.100.42",
	// The User-Agent request header is a string that lets servers 
	// and network peers identify the application, operating system, 
	// vendor, and/or version of the requesting user agent
	"user_agent": "Mozilla/5.0 (platform; rv:geckoversion) Gecko/geckotrail Firefox/firefoxversion",
	// External type takes any value that is being passed
	"external_type": "xyz",
	// A SubID is a string of alphanumeric characters generated at the end 
	// of a redirect URL, which records a user-defined variable
	"sub_ids": [
				"chskadycgbchb",
				"sdjvkhckjsckd"
	]
}

When this event is received, PartnerStack will attribute the user (customer) to the Partner who owns the link the customer clicked on.

Once this attribution is made, the partner can receive rewards when this customer reaches certain business milestones (purchase, subscription renewal, etc).

These milestones and incentives are configured separately in your PartnerStack account.

Example CURL

curl --location --request POST 'https://partnerlinks.io/conversion/xid' \
--header 'Authorization: Bearer <TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "customer_key": "customer_s2s_1",
    "xid": "<XID>",
    "email": "[email protected]",
    "name": "Example Customer Name",
    "origin": "acme.com",
    "ip_address": "198.51.100.42",
    "user_agent": "Mozilla/5.0 (platform; rv:geckoversion) Gecko/geckotrail Firefox/firefoxversion",
	  "external_type": "xyz",
	  "sub_ids": [
        "chskadycgbchb",
        "sdjvkhckjsckd"
	  ]
}'

Responses

CodeDescription
200Conversion created
400Missing required data
401Unauthorized