Tutorial

Setting up a Marketing Partner

This guide shows you how to create a new Marketing Partner and how to join a loyalty program. Furthermore, we look at how you can use the Fanpoints SDK to let users collect and spend FanPoints in your app or website.

Creating a new Marketing Partner

Joining a Loyalty Program

Open the newly created partner and navigate to the Loyalty Programme tab. You can send a request to join a loyalty program. This will allow users in this loyalty program to interact in your app. It might take a few days until the loyalty program (hopefully) accepts your request.

Give out FanPoints using the dashboard

You can give out FanPoints to your users using the Fanpoints dashboard. Click on the Distribute FanPoints button in order to distribute FanPoints to your customers.

Give out FanPoints using the Fanpoints POS app

If you want users to collect and spend FanPoints in your physical stores without any further integration, you can use the Fanpoints partner app. Find out more about the Fanpoints POS app here.

Setting up the Fanpoints SDK

Now you are ready to integrate the Fanpoints SDK into your infrastructure. You can use the SDK to let users collect and spend FanPoints.

Currently, only a server-side typescript SDK is available. It needs to be used in your backend, as user-level authorization is not yet supported. We are working on a client-side SDK that will allow you to use the SDK in your client-side code.

Installing the SDK

You can install the SDK using npm:

npm install @fanpoints/server-js

Getting access tokens

To access the Fanpoints API, you first need to generate access tokens. Go to the dashboard, navigate to your partner, click on Einstellungen and then on API Tokens. You can generate a new token there. Each token consists of a client id and a secret.

Configuring a client

All operations are performed on a FanPointsClient object. With the generated access tokens, you can create a client for your partner:

import { createClient } from '@fanpoints/server-js';

const client = createClient({
    defaultPartnerConfig: {
        partnerId: 'the partner id', // can be found in the dashboard
        clientId: 'the client id',
        secret: 'the client secret',
        defaultCurrency: 'chf',
    },
});

You can use the ping function to test if the client is working:

client.ping().then(() => {
    console.log('The client is working!');
});

Using the Fanpoints SDK

In the following, we will use the Example Loyalty Program to demonstrate how to use the configured Fanpoints client. If you want to follow the tutorial, make sure to join the Example Loyalty Program.

Distributing FanPoints

Let’s assume you want to distribute FanPoints to a user upon a purchase at your store.

You first need to get the Fanpoints user id, for example by letting users enter their id in your app or website as part of the purchase process.

Every distribution of FanPoints is associated with a purchase. A purchase consists of one or more items. The price of the items determines the amount of FanPoints that are distributed to the user. For now, we will use the default commission of 2% which will be distributed as FanPoints. You can use commission rate labels to customize the rates.

const result = await client.fanPoints.giveFanPointsOnPurchase(
    'user-a',   // this is a known user of the Example Loyalty Program
    [
        {
            title: 'T-Shirt',
            description: 'T-Shirt off-white (women, size M)',
            price: 70.0,
        },
        {
            title: 'Socks',
            description: 'Socks black (size S)',
            price: 10.0,
        },
    ]
);

/**
 *  result = [
 *    {
 *      "purchaseId": "<purchase-id>",
 *      "userId": "user-a",
 *      "transactionType": "distributed_on_purchase",
 *      "purchaseItems": [
 *        {
 *          "purchaseItemId": "<purchase-item-id>",
 *          "partnerId": "<your partner id>",
 *          "title": "T-Shirt",
 *          "description": "T-Shirt off-white (women, size M)",
 *          "price": 70,
 *          "currency": "chf",
 *          "amount": 70,
 *          "rateLabel": null,
 *          "date": "2024-02-17 12:08:43.488364"
 *        },
 *        {
 *          "purchaseItemId": "<purchase-item-id>",
 *          "partnerId": "<your partner id>",
 *          "title": "Socks",
 *          "description": "Socks black (size S)",
 *          "price": 10,
 *          "currency": "chf",
 *          "amount": 10,
 *          "rateLabel": null,
 *          "date": "2024-02-17 12:08:43.488364"
 *        }
 *      ]
 *    }
 *  ]
 * /

Purchasing with FanPoints

Letting users purchase items with FanPoints is as easy as distributing them. You can use the purchaseWithFanPoints function to let users purchase items with FanPoints:

const result = await client.fanPoints.payPurchaseWithFanPoints(
    'user-a', // this is a known user of the Example Loyalty Program
    [
        {
            title: 'T-Shirt',
            description: 'T-Shirt off-white (women, size M)',
            price: 70.0,
        },
        {
            title: 'Socks',
            description: 'Socks black (size S)',
            price: 10.0,
        },
    ],
);

/**
 *  result = [
 *    {
 *      "purchaseId": "<purchase-id>",
 *      "userId": "user-a",
 *      "transactionType": "purchased_with_fanpoints",
 *      "purchaseItems": [
 *        {
 *          "purchaseItemId": "<purchase-item-id>",
 *          "partnerId": "<your partner id>",
 *          "title": "T-Shirt",
 *          "description": "T-Shirt off-white (women, size M)",
 *          "price": 70.0,
 *          "currency": "chf",
 *          "amount": -7000,
 *          "rateLabel": null,
 *          "date": "2024-02-17 12:12:34.824832"
 *        },
 *        {
 *          "purchaseItemId": "<purchase-item-id>",
 *          "partnerId": "<your partner id>",
 *          "title": "Socks",
 *          "description": "Socks black (size S)",
 *          "price": 10.0,
 *          "currency": "chf",
 *          "amount": -1000,
 *          "rateLabel": null,
 *          "date": "2024-02-17 12:12:34.824832"
 *        }
 *      ]
 *    }
 *  ]
 * /

The purchaseWithFanPoints function will throw a RequestError if the user does not have enough FanPoints to purchase the items. You can catch this error and handle it in your app or website:

try {
    const result = await client.fanPoints.payPurchaseWithFanPoints(
       ...
    );
} catch (error) {
    if (error.errors?.includes('tooFewAvailableError')) {
        console.log(
            'The user does not have enough FanPoints to purchase the items.',
        );
    } else {
        // another error occurred
        throw error;
    }
}

If you want to check the FanPoints balance before the purchase, you can use the following method to check the number of FanPoints the user has collected and the corresponding monetary value of the FanPoints:

const balance = await client.fanPoints.getBalance('user-a');
// balance = { fanPoints: 3465, monetaryValue: 34.65, currency: 'chf' }

You can also use the following method to check the number of FanPoints a user would have to spend to purchase a given item:

const fanPointsNeeded = await client.fanPoints.getPriceInFanPoints(70.0);
// fanPointsNeeded = 7000

Next steps

You can now use the Fanpoints SDK to let users collect and spend FanPoints in your app or website. If you want to learn more about the SDK, check out the other parts of the documentation.