Marketplace

This page describes how to use the marketplace module of the FanPoints SDK.

General concepts

The marketplace allows you to offer unique products to your users.

Products are provided by Marketing Partners. Generally, a product object has the following properties:

{
    rewardType: "Product";
    title: string;
    description: string;
    imageUrls: string[];
    productCategory: "experience" | "memorabilia" | "product";
    partner: {
        branding: {
            logoColorUrl: undefined | string;
        };
        name: string;
        partnerId: string;
    };
}

Users can obtain products through different distribution channels:

• Purchase: Users can purchase products with FanPoints. This distribution channel has the following properties:

  {
      distributionType: 'ShopPurchaseDistributionPolicy';
      distributionPolicyId: string;
      price: number;
      currency: 'fp';
  }

• Lottery: Users can purchase lottery tickets with FanPoints. The product will be randomly distributed among all the ticket holders. This distribution channel has the following properties:

  {
      distributionType: 'ShopLotteryDistributionPolicy';
      distributionPolicyId: string;
      lotteryStartDate: string;
      lotteryEndDate: string;
      numTicketsToDraw: number;
      ticketPrice: number;
      currency: 'fp';
      lotteryStatus: 'drawn' |
          'not_yet_drawn' |
          'partially_drawn' |
          'too_few_available' |
          'too_few_tickets';
  }

• Auction: Users can place bids with FanPoints. The product is then sold to the highest bidder. This distribution channel has the following properties:

  {
      distributionType: 'ShopAuctionDistributionPolicy';
      distributionPolicyId: string;
      auctionStartDate: string;
      auctionEndDate: string;
      currency: 'fp';
      minBid: number;
      auctionStatus: 'distributed' | 'not_yet_distributed' | 'too_few_available' | 'too_few_bids';
  }

• Lootbox: Users can obtain products for free by opening lootboxes. This distribution channel is not part of the marketplace.

Creating your marketplace

To create your own marketplace, you just have to provide add its frontend to your existing infrastructure. Fanpoints provides the entire backend for you. Your Marketing Partners create and manage the products.

Displaying marketplace items

The marketplace is a simple list of products with attached distribution channels. You can get the marketplace items using the following snippet:

const items = await loyaltyProgramClient.marketplace.getMarketplaceItems();
console.log(JSON.stringify(result));

/**
 * [
 *      {
 *         "rewardId": "<reward id>",
 *         "partnerId": "<partner id>",
 *         "product": {
 *             "rewardType": "Product",
 *             "title": "Gnochetti",
 *             "description": "These are the best gnochettis north of Italy.",
 *             "productCategory": "product",
 *             "imageUrls": [
 *                 "<some url>"
 *             ],
 *             "partner": {
 *                 "partnerId": "<partner id>",
 *                 "name": "<partner name>",
 *                 "branding": {
 *                     "logoColorUrl": "<some url>"
 *                 }
 *             }
 *         },
 *         "distributionPolicy": {
 *             "distributionType": "ShopPurchaseDistributionPolicy",
 *             "distributionPolicyId": "<distribution policy id>",
 *             "price": 500,
 *             "currency": "fp"
 *         }
 *     }
 * ]
 */

The distributionPolicy property can take any of the shapes described above. You can use the distributionType to determine which shape to use (TypeScript should perform automatic type narrowing).

The getMarketplaceItems has arguments allowing you to filter the items by product category and to paginate the results.

Displaying a single marketplace item

To display a single item, you can use the following snippet:

const result = await loyaltyProgramClient.marketplace.getMarketplaceItem(
    '<rewardId>',
    '<distributionPolicyId>',
    '<partnerId>'
);
console.log(JSON.stringify(result, null, 4));

/**
 * {
 *    "rewardId": "<reward id>",
 *    "partnerId": "<partner id>",
 *    "product": {
 *        "rewardType": "Product",
 *        "title": "Gnochetti",
 *        "description": "These are the best gnochettis north of Italy.",
 *        "productCategory": "product",
 *        "imageUrls": [
 *            "<some url>"
 *        ],
 *        "partner": {
 *            "partnerId": "<partner id>",
 *            "name": "<partner name>",
 *            "branding": {
 *                "logoColorUrl": "<some url>"
 *            }
 *        }
 *    },
 *    "distributionPolicy": {
 *        "distributionType": "ShopPurchaseDistributionPolicy",
 *        "distributionPolicyId": "<distribution policy id>",
 *        "price": 500,
 *        "currency": "fp"
 *    }
 * }
 */

What identifies a marketplace item?

You might have noticed that the getMarketplaceItem method takes three arguments. The rewardId is the id of the product itself, the partnerId is the id of the partner who created the product. Because a partner can attach multiple distribution policies to a product, the distributionPolicyId is also needed to identify a marketplace item. A marketplace item always consists of a product and a distribution policy.

Purchasing marketplace items

You can let users purchase marketplace items with a ShopPurchaseDistributionPolicy using the following snippet:

await loyaltyProgramClient.marketplace.purchaseItem(
    "<user_id>",
    "<reward_id>",
    "<distribution_policy_id>",
    "<partner_id>",
    1,  // quantity
    "John Doe",  // delivery address name
    {   // delivery address
        "zip_code": "8001",
        "street": "Bahnhofstrasse 1",
        "country": "CH",
        "city": "Zürich"
    }
);

What about errors?

As always, an error will be thrown if the user does not have enough FanPoints to purchase the item. You can catch this error and handle it in your app or website:

try {
    await loyaltyProgramClient.marketplace.purchaseItem(
        "<user_id>",
        "<reward_id>",
        "<distribution_policy_id>",
        "<partner_id>",
        1000,    // the user does not have enough FP for that many
        "John Doe",  // delivery address name
        {   // delivery address
            "zip_code": "8001",
            "street": "Bahnhofstrasse 1",
            "country": "CH",
            "city": "Zürich"
        }
    );
} catch (error) {
    console.log(error.errors)   // [ 'tooFewAvailableError' ]
}

Purchasing lottery tickets

You can let users purchase lottery tickets with a ShopLotteryDistributionPolicy using the following snippet:

await loyaltyProgramClient.marketplace.purchaseLotteryTicket(
    "<user_id>",
    "<reward_id>",
    "<distribution_policy_id>",
    "<partner_id>",
    1,  // quantity
    "John Doe",  // delivery address name
    {   // delivery address
        "zip_code": "8001",
        "street": "Bahnhofstrasse 1",
        "country": "CH",
        "city": "Zürich"
    }
);

Auctions

Auctions allow users to place bids with FanPoints. A user can place as many bids as they want. There is a minimum bid that has to be placed, and the current highest bid has to be surpassed by the new bid by a certain amount.

To get information about the current status of an auction, you can use the following snippet:

const result = await loyaltyProgramClient.marketplace.getAuctionStatus(
    "<user_id>",
    "<reward_id>",
    "<distribution_policy_id>",
    "<partner_id>",
);
console.log(JSON.stringify(result, null, 4));

/**
 * {
 *   isAuctionOpen: true,
 *   bids: [
 *     {
 *       bidderId: '<bidderId>',
 *       date: '2024-08-15 09:24:38.259743+00:00',
 *       fanPoints: 5000,
 *       byCurrentUser: true
 *     }
 *   ],
 *   currentHighestBid: 5000,
 *   currentUserBid: 5000,
 *   nextHigherBid: 5050,
 *   isUserHighestBidder: true
 * }
 */

To place a bid, you can use the following snippet:

await loyaltyProgramClient.marketplace.bidOnItem(
    "<user_id>",
    "<reward_id>",
    "<distribution_policy_id>",
    "<partner_id>",
    5000,   // the number of FP to bid with
    "John Doe",  // delivery address name
    {   // delivery address
        "zip_code": "8001",
        "street": "Bahnhofstrasse 1",
        "country": "CH",
        "city": "Zürich"
    }
)

Displaying the obtained marketplace items

A user should be able to see the obtained products. You can use the following snippet to get the obtained products:

const result = await loyaltyProgramClient.marketplace.getObtainedProducts(
    "<user_id>",
);
console.log(JSON.stringify(result, null, 4));

/**
 * [
 *     {
 *         "product": {
 *             "rewardType": "Product",
 *             "rewardId": "<reward id>",
 *             "title": "Gnochetti",
 *             "description": "These are the best gnochettis north of Italy",
 *             "productCategory": "product",
 *             "imageUrls": [
 *                 "<some url>"
 *             ],
 *             "partner": {
 *                 "partnerId": "<partner id>",
 *                 "name": "<partner name>",
 *                 "branding": {
 *                     "logoColorUrl": "<some url>"
 *                 }
 *             },
 *             "deliveryStatus": "delivered",
 *             "deliveryDate": "2024-07-29 10:15:21.261221+00:00"
 *         },
 *         "transactionGroupId": "<transaction group id>",
 *         "transactionNr": 0,
 *         "deliveryDetails": {
 *             "deliveryAddress": {
 *                 "zipCode": "8001",
 *                 "street": "Bahnhofstrasse 1",
 *                 "country": "CH",
 *                 "city": "Zürich"
 *             },
 *             "deliveryName": "John Doe",
 *         },
 *         "purchaseDate": "2024-07-29 09:53:42.756790+00:00"
 *     }
 * ]
 */