Conversion module

The conversion module contains methods revolving around purchases by Fanpoints users at Marketing Partners. It allows you to give users FanPoints on purchases and to let users pay with FanPoints. Furthermore, some convenience methods such as retrieving registered purchases or converting FanPoints to CHF are provided.

Distributing FanPoints to users

One key feature of the Fanpoints ecosystem is that users can collect FanPoints when making purchases at Marketing Partners like yourself.

The only information that is required to distribute FanPoints to a user is the user id. One common way to get the user id is to add an input field to your checkout form.

Validating user ids

The user module contains methods to validate user ids.

The API takes a list of the purchase items and their price in CHF as an argument. The conversion from CHF to FanPoints is performed automatically by Fanpoints. You can set different commission rates in the dashboard (Navigate to Conversion and then Provisions-Modelle). Use the rate_label argument to specify the commission rate label (see the examples below).

Estimate how many FanPoints a user would receive for a purchase

It might be a good idea to display the number of FanPoints a user would receive for a purchase. You can use the estimate_given_out_fan_points_on_purchase method to do that.

import asyncio
from fanpoints_python import FanpointsClient
from fanpoints_python.types import PurchaseItemPriceInput, Currency

client = FanpointsClient(
    partner_id='<your partner id>',
    client_id='<your client id>',
    secret='<your client secret>',
)

async def run():
    result = await client.conversion.estimate_given_out_fanpoints_on_purchase(
        [
            PurchaseItemPriceInput(
                price=20.0,
                currency=Currency.chf,
            ),
            PurchaseItemPriceInput(
                price=15.0,
                currency=Currency.chf,
                rate_label="<one of your rate labels>",
            ),
        ]
    )
    print(result)   # "175" in this example

asyncio.run(run())

Distributing FanPoints to a user

Once a user has performed a purchase, you can use the give_fan_points_on_purchase method to distribute the FanPoints to the user:

import asyncio
from fanpoints_python import FanpointsClient
from fanpoints_python.types import PurchaseItemInput, Currency

client = FanpointsClient(
    partner_id='<your partner id>',
    client_id='<your client id>',
    secret='<your client secret>',
)

async def run():
    result = await client.conversion.give_fanpoints_on_purchase(
        user_id="<user_id>",
        purchase_items=[
            PurchaseItemInput(
                title="Jersey Season 24/25 Men",
                description="The legendary new jersey everyone is talking about! It's on fire.",
                price=45.0,
                currency=Currency.chf,
            ),
            PurchaseItemInput(
                title="Fan-Pin",
                description="The best way to display your support for the team.",
                price=5.0,
                currency=Currency.chf,
                rate_label="<one of your rate labels (optional)>",
                custom_purchase_item_id="<custom_purchase_item_id (optional)>",
            ),
        ],
        custom_purchase_id="<custom_purchase_id (optional)>",
    )

    print(result.model_dump_json(indent=2))
    """
    {
        "purchase_id": "<purchase_id>",
        "user_id": "<user_id>",
        "transaction_type": "distributed_on_purchase",
        "purchase_items": [
            {
                "purchase_item_id": "<purchase_item_id",
                "partner_id": "<partner_id>",
                "title": "Jersey Season 24/25 Men",
                "description": "The legendary new jersey everyone is talking about! It's on fire.",
                "price": 45.0,
                "currency": "chf",
                "amount": 225,
                "rate_label": null,
                "date": "2024-08-03 09:26:17.108815+00:00",
                "has_been_undone": false,
                "has_been_settled": false
            },
            {
                "purchase_item_id": "<purchase_item_id",
                "partner_id": "<partner_id>",
                "title": "Fan-Pin",
                "description": "The best way to display your support for the team.",
                "price": 5.0,
                "currency": "chf",
                "amount": 25,
                "rate_label": <your chosen rate label>,
                "date": "2024-08-03 09:26:17.108815+00:00",
                "has_been_undone": false,
                "has_been_settled": false
            }
        ]
    }
    """

asyncio.run(run())

As before, you can choose a different commission rate label for every purchase item. You can also choose to set a custom_purchase_id and different custom_purchase_item_id’s. This allows you to connect the purchase to your internal systems. Note that these ids must be unique for each purchase that you register. If you don’t set them, the Fanpoints API will generate them for you.

Note

As always, the return values of the give_fanpoints_on_purchase are fully typed pydantic models.

Letting users pay with FanPoints

You can also let users pay with FanPoints.

Getting the price in FanPoints

It can be useful to display the price in FanPoints to your users. You can use the get_price_in_fan_points method to do that:

import asyncio
from fanpoints_python import FanpointsClient
from fanpoints_python.types import Currency

client = FanpointsClient(
    partner_id='<your partner id>',
    client_id='<your client id>',
    secret='<your client secret>',
)

async def run():
    result = await client.conversion.get_price_in_fan_points(
        price=10.0,
        currency=Currency.chf,
    )
    print(result)   # 5000

asyncio.run(run())

Paying with FanPoints

You can use Fanpoints as a payment service provider (PSP) to let users pay with FanPoints. Use the pay_purchase_with_fan_points method to do that:

import asyncio
from fanpoints_python import FanpointsClient
from fanpoints_python.types import PurchaseItemInput, Currency

client = FanpointsClient(
    partner_id='<your partner id>',
    client_id='<your client id>',
    secret='<your client secret>',
)

async def run():
    result = await client.conversion.pay_purchase_with_fanpoints(
        user_id="<user_id>",
        purchase_items=[
            PurchaseItemInput(
                title="Fan-Pin",
                description="The best way to display your support for the team.",
                price=10.0,
                currency=Currency.chf,
                custom_purchase_item_id="<custom_purchase_item_id (optional)>",
            ),
        ],
        custom_purchase_id="<custom_purchase_id (optional)>",
    )

    print(result.model_dump_json(indent=2))
    """
    {
        "purchase_id": "<purchase_id>",
        "user_id": "user_id",
        "transaction_type": "purchased_with_fanpoints",
        "purchase_items": [
            {
                "purchase_item_id": "purchase_item_id",
                "partner_id": "<partner_id>",
                "title": "Fan-Pin",
                "description": "The best way to display your support for the team.",
                "price": 10.0,
                "currency": "chf",
                "amount": 5000,
                "rate_label": null,
                "date": "2024-08-03 10:37:14.534830+00:00",
                "has_been_undone": false,
                "has_been_settled": true
            }
        ]
    }
    """

As with the give_fanpoints_on_purchase method, you can set a custom_purchase_id and custom_purchase_item_id to connect the purchase to your internal systems.

Note

For purchasing with FanPoints, the FanPoints to CHF rate is fixed and can not be set by the Marketing Partner by using the rate_label argument.

Retrieving registered purchases

You can use the get_purchases method to retrieve all registered purchases:

import asyncio
from fanpoints_python import FanpointsClient

client = FanpointsClient(
    partner_id='<your partner id>',
    client_id='<your client id>',
    secret='<your client secret>',
)

async def run():
    result = await client.conversion.get_purchases()

    for purchase in result:
        print(purchase.model_dump_json(indent=2))

    """
    {
        "purchase_id": "<purchase_id>",
        "user_id": "<user_id>",
        "transaction_type": "distributed_on_purchase",
        "purchase_items": [
            {
                "purchase_item_id": "<purchase_item_id",
                "partner_id": "<partner_id>",
                "title": "Jersey Season 24/25 Men",
                "description": "The legendary new jersey everyone is talking about! It's on fire.",
                "price": 45.0,
                "currency": "chf",
                "amount": 225,
                "rate_label": null,
                "date": "2024-08-03 09:26:17.108815+00:00",
                "has_been_undone": false,
                "has_been_settled": false
            },
            {
                "purchase_item_id": "<purchase_item_id",
                "partner_id": "<partner_id>",
                "title": "Fan-Pin",
                "description": "The best way to display your support for the team.",
                "price": 5.0,
                "currency": "chf",
                "amount": 25,
                "rate_label": null,
                "date": "2024-08-03 09:26:17.108815+00:00",
                "has_been_undone": false,
                "has_been_settled": false
            }
        ]
    }
    """

asyncio.run(run())

The get_purchases method has an optional argument user_id that allows you to filter the purchases by user id. Furthermore, you can use the earlier_than and limit arguments to paginate the results.

Caution

All datetimes have to be time-zone aware. All returned datetimes are also aware.

Retrieving a single purchase

You can use the get_purchase method to retrieve a single purchase:

import asyncio
from fanpoints_python import FanpointsClient

client = FanpointsClient(
    partner_id='<your partner id>',
    client_id='<your client id>',
    secret='<your client secret>',
)

async def run():
    result = await client.conversion.get_purchase(
        user_id="<user_id>",
        purchase_id="<purchase_id>"
    )

    print(result.model_dump_json(indent=2))
    """
    {
        "purchase_id": "<purchase_id>",
        "user_id": "<user_id>",
        "transaction_type": "distributed_on_purchase",
        "purchase_items": [
            {
                "purchase_item_id": "<purchase_item_id",
                "partner_id": "<partner_id>",
                "title": "Jersey Season 24/25 Men",
                "description": "The legendary new jersey everyone is talking about! It's on fire.",
                "price": 45.0,
                "currency": "chf",
                "amount": 225,
                "rate_label": null,
                "date": "2024-08-03 09:26:17.108815+00:00",
                "has_been_undone": false,
                "has_been_settled": false
            },
            {
                "purchase_item_id": "<purchase_item_id",
                "partner_id": "<partner_id>",
                "title": "Fan-Pin",
                "description": "The best way to display your support for the team.",
                "price": 5.0,
                "currency": "chf",
                "amount": 25,
                "rate_label": null,
                "date": "2024-08-03 09:26:17.108815+00:00",
                "has_been_undone": false,
                "has_been_settled": false
            }
        ]
    }
    """

Cancelling a purchase

If an already-made purchase is canceled, you can use the undo_purchase method to undo single purchase items. This works for both purchases where the user has been given FanPoints and purchases where the user has paid with FanPoints.

import asyncio
from fanpoints_python import FanpointsClient

client = FanpointsClient(
    partner_id='<your partner id>',
    client_id='<your client id>',
    secret='<your client secret>',
)

async def run():
    result = await client.conversion.undo_purchase_item(
        user_id="<user_id>",
        purchase_id="<purchase_id>",
        purchase_item_id="<purchase_item_id>",
    )

    print(result.model_dump_json(indent=2))
    """
    {
        "purchase_id": "<undo_purchase_id>",
        "user_id": "<user_id>",
        "transaction_type": "undo_distributed_on_purchase",
        "purchase_items": [
            {
                "purchase_item_id": "<undo_purchase_item_id",
                "partner_id": "<partner_id>",
                "title": "Jersey Season 24/25 Men",
                "description": "The legendary new jersey everyone is talking about! It's on fire.",
                "price": 45.0,
                "currency": "chf",
                "amount": -225,
                "rate_label": null,
                "date": "2024-08-03 10:14:55.100755+00:00",
                "has_been_undone": false,
                "has_been_settled": false
            }
        ]
    }
    """

asyncio.run(run())

Note

Cancelling a purchase item will not remove the purchase itself. Instead, an undo-transaction is created with a negative FanPoints amount and a transaction_type of either undo_distributed_on_purchase or undo_purchased_with_fanpoints. Furthermore, the has_been_undone flag of the original purchase item is set to true.

get_purchases will also return undo-transactions for purchases.