Set up payment attribution

Payment attribution helps you identify which content creator’s link referred to the user who made the purchase. All purchases made by that user are linked to the creator, so they can receive accurate payouts based on campaign results.

How it works

To enable attribution, use the tracking_id parameter.

The tracking_id is a unique identifier that links a user’s payment to a traffic source (e.g., an advertising campaign). It is used to:

track the performance of campaigns
identify which creator referred the user
collect analytics in Partner Network
correctly calculate rewards and payouts

The tracking_id is generated by Xsolla when a user clicks a content creator’s personal link. As the user follows this link, Xsolla automatically appends the tracking_id parameter, a unique 32-character identifier, to the URL. The link may point to the Web Shop’s main page, a specific item, or a promotion, depending on the campaign. You must pass the tracking_id in the request to generate a payment token. After the transaction is completed, the tracking_id is saved with the payment data and is used for attribution, analytics, and financial reporting.

Example: https://webshop-external-demo.xsolla.site/?tracking_id=abcdefghijklmnopqrstuvwxyz123456

If tracking_id is not passed, the payment won’t be attributed to a traffic source, won’t appear in the performance report, and won’t be included in payouts to creators.

To pass tracking_id when generating a payment token:

Get the tracking_id from the query parameters in the URL.
Save it to the browser's localStorage.
Include tracking_id in the request to generate the payment token.

Get tracking_id

Getting the tracking_id parameter on the client side depends on your integration type. You can either implement your own logic for extracting tracking_id, or use the Partner Network tracking script provided by Xsolla.

Make sure the script runs before any other JavaScript that modifies the URL. Otherwise, the tracking_id may be lost.

We recommend using the Partner Network tracking script — it automatically saves tracking_id to localStorage and provides access to the getTrackingId() method.

Detailed implementation examples are provided in the tabs below.

The snippet below extracts the tracking_id from the URL and saves it to localStorage. Use this code if you don’t plan to use the Partner Network tracking script.

tracking_id processing snippet:

Copy

Full screen

Small screen

 1(function () {
 2  const XPN_TRACKING_ID = 'xsolla_partner_network_tracking_id';
 3  const TRACKING_ID = 'tracking_id';
 4
 5  function removeTrackingIdFromUrl() {
 6    if (window.history && window.history.replaceState) {
 7      const url = new URL(window.location.href);
 8      url.searchParams.delete(TRACKING_ID);
 9      window.history.replaceState(null, '', url.toString());
10    }
11  }
12
13  function extractTrackingIdFromURL() {
14    try {
15      const savedTrackingId = localStorage.getItem(XPN_TRACKING_ID);
16      const searchParams = new URLSearchParams(window.location.search);
17      const trackingId = searchParams.get(TRACKING_ID) || savedTrackingId || '';
18      if (trackingId !== '') {
19        localStorage.setItem(XPN_TRACKING_ID, trackingId);
20      }
21      removeTrackingIdFromUrl();
22    } catch (e) {
23      console.error('[Xsolla Partner Network] Failed to extract tracking_id:', e);
24    }
25  }
26
27  function getTrackingId() {
28    return localStorage.getItem(XPN_TRACKING_ID) || null;
29  }
30
31  extractTrackingIdFromURL();
32  window.XsollaPartnerNetwork = window.XsollaPartnerNetwork || {};
33  window.XsollaPartnerNetwork.getTrackingId = getTrackingId;
34})();

This script automatically extracts the tracking_id from the URL’s query parameters, saves it to localStorage, and provides the getTrackingId() method to use when generating a payment token.

Add the following script to the HTML of your Web Shop:

Copy

Full screen

Small screen

1<script src="https://cdn.xsolla.net/xpn-bucket-prod/xpn-script/xpn@latest/xpn.min.js"></script>

The script must be loaded on all pages where a payment token may be generated.

Example:

Copy

Full screen

Small screen

1const trackingId = XsollaPartnerNetworkSDK.getTrackingId();
2if (trackingId) {
3  console.log('Saved tracking_id from URL:', trackingId);
4  // add tracking_id into your request parameters
5}

Pass tracking_id when generating payment token

Depending on how your integration is set up, use one of the options below to pass the tracking_id to the token generation method.

To ensure accurate attribution, make sure tracking_id is included in the token request.

To pass tracking_id to the purchase widget:

Get the tracking_id on the client side (e.g., from the URL or localStorage).
Add it to access_data.user.tracking_id.value parameter during widget initialization:

Copy

Full screen

Small screen

1{
2 access_data: {
3  user: {
4    tracking_id: {
5      value: "abcdefghijklmnopqrstuvwxyz123456"
6    }
7  }
8}
9}

Passing tracking_id via access_data is deprecated. We recommend using access_token similar to Pay Station Embed.

tracking_id can’t be passed as a widget initialization parameter. Instead, it must be included in the token’s parameter user.tracking_id.value.

To pass tracking_id to Pay Station Embed:

Get the tracking_id on the client side (e.g., from the URL or localStorage).
Pass this parameter while generating payment token:

Copy

Full screen

Small screen

1{
2  "user": {
3    "tracking_id": {
4      "value": "abcdefghijklmnopqrstuvwxyz123456"
5    }
6  }
7}

Use the access_token to initialize the widget:

Copy

Full screen

Small screen

1XPayStationWidget.init({
2  access_token: 'your_token_with_tracking_id'
3});

Using access_data instead of access_token is deprecated. If your integration doesn’t support access_token, pass tracking_id in the access_data.user.tracking_id.value parameter – as shown in the purchase widget.

To pass tracking_id with Headless checkout:

Get the tracking_id on the client side (e.g., from the URL or localStorage).
Add it to user.tracking_id.value parameter while generating payment token.
Initialize the SDK using the headlessCheckout.init() method.
Pass the token using:

Copy

Full screen

Small screen

1await headlessCheckout.setToken('your_token_with_tracking_id');

Payment token on client side

Use this option if you generate the payment token via one of the following API calls:

To pass tracking_id while generating payment token:

Get the tracking_id on the client side (e.g., from the URL or localStorage).
Add it to the user.tracking_id.value parameter.

Example:

Copy

Full screen

Small screen

1{
2  "user": {
3    "tracking_id": {
4      "value": "abcdefghijklmnopqrstuvwxyz123456"
5    }
6  }
7}

This option is client-side only. Country and currency are determined by the user’s IP address.

Payment token on the server side

Use this option if you generate the payment token via the Create payment token for purchase API call.

To pass tracking_id while generating payment token:

Get the tracking_id on the client side (e.g., from the URL or localStorage).
Add it to the user.tracking_id.value parameter.

Example:

Copy

Full screen

Small screen

1{
2  "user": {
3    "tracking_id": {
4      "value": "abcdefghijklmnopqrstuvwxyz123456"
5    }
6  }
7}

To pass tracking_id using SDK for Unity:

Make sure you’re using a recent SDK version that supports tracking_id.
Get tracking_id on the client side (e.g., via deeplink).
Pass it to the Xsolla.Core.PurchaseParams object (SDK for Unity).

Example:

Copy

Full screen

Small screen

1var purchaseParams = new PurchaseParams {
2  tracking_id = "abcdefghijklmnopqrstuvwxyz123456"
3};

Thank you for your feedback!

We’ll review your message and use it to help us improve your experience.

Last updated: September 23, 2025

Found a typo or other text error? Select the text and press Ctrl+Enter.

Contents

How it works
Get tracking_id
Pass tracking_id when generating payment token
Payment token on client side
Payment token on the server side

Your browser is not supported. Please try a different browser

Set up payment attribution

How it works

Get tracking_id

Pass tracking_id when generating payment token

Payment token on client side

Payment token on the server side