FanPoints Management

This page contains more in-depth information about how to manage FanPoints for a user as a Marketing Partner.

Access the transactions of a user at a Marketing Partner

As a Marketing Partner, you can access the transactions of a user at your store using the following code. Every transaction represents a purchase where the user has been given FanPoints or a purchase that the user has payed with FanPoints.

const transactions = await client.fanPoints.getTransactions('user id');

/**
 * transactions = [
 *   {
 *     purchaseId: <purchase Id>
 *     userId: <user id>,
 *     transactionType: "purchased_with_fanpoints",
 *     purchaseItems: [
 *       {
 *         purchaseItemId: <purchase item id>,
 *         partnerId: <partner id>,
 *         partner: {
 *              name: "<name>",
 *              description: "<description>",
 *              website: "<website>",
 *              branding: {
 *                  logoUrl: "<logo url>"
 *              }
 *         },
 *         title: <title>,
 *         description: <description>,
 *         price: <price in CHF>,
 *         currency: "chf",
 *         amount: <price in FanPoints>,
 *         rateLabel: <commission rate label>,
 *         date: <date of purchase>,
 *       },
 *       {
 *         purchaseItemId: <purchase item id>,
 *         partnerId: <partner id>,
 *         partner: {
 *              name: "<name>",
 *              description: "<description>",
 *              website: "<website>",
 *              branding: {
 *                  logoUrl: "<logo url>"
 *              }
 *         },
 *         title: <title>,
 *         description: <description>,
 *         price: <price in CHF>,
 *         currency: "chf",
 *         amount: <price in FanPoints>,
 *         rateLabel: <commission rate label>,
 *         date: <date of purchase>,
 *       },
 *     ],
 *   },
 *   {
 *     purchaseId: <purchase Id>
 *     userId: <user id>,
 *     transactionType: "distributed_on_purchase",
 *     purchaseItems: [
 *       {
 *         purchaseItemId: <purchase item id>,
 *         partnerId: <partner id>,
 *         partner: {
 *              name: "<name>",
 *              description: "<description>",
 *              website: "<website>",
 *              branding: {
 *                  logoUrl: "<logo url>"
 *              }
 *         },
 *         title: <title>,
 *         description: <description>,
 *         price: <price in CHF>,
 *         currency: "chf",
 *         amount: <recieved FanPoints>,
 *         rateLabel: <commission rate label>,
 *         date: <date of purchase>,
 *       },
 *       {
 *         purchaseItemId: <purchase item id>,
 *         partnerId: <partner id>,
 *         partner: {
 *              name: "<name>",
 *              description: "<description>",
 *              website: "<website>",
 *              branding: {
 *                  logoUrl: "<logo url>"
 *              }
 *         },
 *         title: <title>,
 *         description: <description>,
 *         price: <price in CHF>,
 *         currency: "chf",
 *         amount: <recieved FanPoints>,
 *         rateLabel: <commission rate label>,
 *         date: <date of purchase>,
 *       },
 *     ],
 *   },
 * ]

You can paginate the results:

// get only the last 10 transactions
client.fanPoints.getTransactions('user id', 10);

// get only the last 10 transactions earlier than the given date
client.fanPoints.getTransactions('user id', 10, new Date());

Give FanPoints to a user after a purchase

Before a user makes a purchase to receive FanPoints, you can use the following operation to know how many FanPoints the user would receive for a purchase consisting of the given purchase items:

const fanpoints = await client.fanPoints.estimateGivenOutFanPointsOnPurchase(
    [
        {
            price: <price in CHF>,  // item 1
        },
        {
            price: <price in CHF>,  // item 2
        },
    ]
);

/**
* fanpoints = <number of fan points the user would receive.>
*/

When a user makes a purchase and you want to give them FanPoints as a partner, you can use the following operation. The first argument specifies the user id, the second argument is an array of purchase items.

client.fanPoints.giveFanPointsOnPurchase('user id', [
    {
        title: 'Ticket',
        description: 'Ticket Category B for SC Azure vs. SC Indigo',
        price: 65.0,
    },
]);

For each purchase item, you can specify a commission rate label that determines how many FanPoints the user gets for every CHF on the purchase. If no rate label is given, the default rate is used. You can configure the different commission rate labels in the dashboard.

client.fanPoints.giveFanPointsOnPurchase('user id', [
    {
        title: 'Ticket',
        description: 'Ticket Category B for SC Azure vs. SC Indigo',
        price: 65.0,
        rateLabel: 'ticket',
    },
    {
        title: 'Shirt men',
        description: 'The current SC Azure shirt for men (size S)',
        price: 100.0,
        rateLabel: 'default',
    },
]);

Furthermore, you can assign each purchase item a specific (potentially different) partner using the partner id or a partner label. Note that the partners must be configured upon creation of the client.

// using partner ids

client.fanPoints.giveFanPointsOnPurchase('user id', [
    {
        title: 'Ticket',
        description: 'Ticket Category B for SC Azure vs. SC Indigo',
        price: 65.0,
        partnerId: 'the partner id',
    },
    {
        title: 'Shirt men',
        description: 'The current SC Azure shirt for men (size S)',
        price: 100.0,
        partnerId: 'the partner id',
    },
]);

// using partner labels

client.fanPoints.giveFanPointsOnPurchase('user id', [
    {
        title: 'Ticket',
        description: 'Ticket Category B for SC Azure vs. SC Indigo',
        price: 65.0,
        partnerLabel: 'partner label',
    },
    {
        title: 'Shirt men',
        description: 'The current SC Azure shirt for men (size S)',
        price: 100.0,
        partnerLabel: 'partner label',
    },
]);

You can set your own purchaseId and your own purchaseItemId’s. This allows to easily connect the purchase items to your internal systems.

client.fanPoints.giveFanPointsOnPurchase(
    'user id',
    [
        {
            title: 'Ticket',
            description: 'Ticket Category B for SC Azure vs. SC Indigo',
            price: 65.0,
            customPurchaseItemId: 'your internal item id',
        },
        {
            title: 'Shirt men',
            description: 'The current SC Azure shirt for men (size S)',
            price: 100.0,
            customPurchaseItemId: 'your internal item id',
        },
    ],
    'your internal purchase id'
);

Pay with FanPoints

When a user wants to pay a purchase with FanPoints, you can use the payPurchaseWithFanPoints operation.

client.fanPoints.payPurchaseWithFanPoints('user id', [
    {
        title: 'Ticket',
        description: 'Ticket Category B for SC Azure vs. SC Indigo',
        price: 65.0,
    },
    {
        title: 'Shirt men',
        description: 'The current SC Azure shirt for men (size S)',
        price: 100.0,
    },
]);

It has the same interface as the giveFanPointsOnPurchase operation: You can also specify the partner id or partner label for each purchase item. Moreover, you can set your own purchaseId and your own purchaseItemId’s.

Undo a purchase

You can undo purchase items connected to a FanPoints transaction using the following snippet. This is usefule when a purchase has been redeemed.

client.fanPoints.undoPurchase('user id', 'purchase id', [
    {
        purchaseItemId: 'purchase item id',
    },
    {
        purchaseItemId: 'purchase item id',
    },
]);

You don’t have to undo all purchase items of a purchase.

If multiple Marketing Partners are configured, you have to specify at which partner you want to undo the purchase using the partner id or one of the partner labels:

client.fanPoints.undoPurchase('user id', 'purchase id', [
    {
        purchaseItemId: 'purchase item id',
        partnerId: 'partner id',
    },
    {
        purchaseItemId: 'purchase item id',
        partnerLabel: 'partner label',
    },
]);