Class MarketplaceModule

This class allows you to display the items in the marketplace, to purchase items and lottery tickets and to place bids. Furthermore, it allows to retrieve purchases done by the user.

Methods

bidOnItem getAuctionStatus getLotteryStatus getMarketplaceItem getMarketplaceItems getObtainedProducts getUserParticipations purchaseItem purchaseLotteryTicket

Methods

bidOnItem

  • bidOnItem(userId, rewardId, distributionPolicyId, partnerId, bid, useAutomaticBidding, deliveryName, deliveryAddress): Promise<undefined>

  • Places a bid on a bidding marketplace item.

    Note that only marketplace items that have a distributionType of ShopAuctionDistributionPolicy can be bid on.

    Only bids higher at least greater than 50 FP than the current highest bid will be accepted. Otherwise, the bid will be rejected (invalidBidAmountError).

    When the auction is over, the bidder with the highest bid will be the winner and purchase the item automatically.

    Parameters

    • userId: string

      The user ID of the user.

    • rewardId: string

      The reward ID of the marketplace item to bid on.

    • distributionPolicyId: string

      The ID of the distribution policy of the marketplace item to bid on.

    • partnerId: string

      The partner ID of the partner offering the marketplace item to bid on.

    • bid: number

      The number of fan points to bid on the item.

    • useAutomaticBidding: boolean

      Whether to use automatic bidding.

    • deliveryName: string

      The name of the person to deliver the item to.

    • deliveryAddress: {
          city: string;
          country: string;
          street: string;
          zip_code: string;
      }

      The address of the person to deliver the item to.

      • city: string
      • country: string
      • street: string
      • zip_code: string

    Returns Promise<undefined>

    Throws

    RequestError if the user does not exist (unknownUserError), if the item does not exist (unknownProductError), if the user does not have enough points to place the bid (tooFewAvailableError), or if the given bid is not valid (invalidBidAmountError).

getAuctionStatus

  • getAuctionStatus(rewardId, distributionPolicyId, partnerId, userId?): Promise<{
        bids: {
            bidderId: string;
            byCurrentUser: undefined | boolean;
            date: string;
            fanPoints: number;
        }[];
        currentHighestBid: number;
        currentUserBid: undefined | number;
        doesUserUseAutomaticBidding: boolean;
        isAuctionOpen: boolean;
        isUserHighestBidder: boolean;
        maxAutomaticBid: undefined | number;
        nextHigherBid: number;
    }>

  • Returns the current status of the auction for a auction marketplace item.

    Parameters

    • rewardId: string

      The reward ID of the item to get the auction status for.

    • distributionPolicyId: string

      The ID of the distribution policy of the item to get the auction status for.

    • partnerId: string

      The partner ID of the partner offering the item to get the auction status for.

    • OptionaluserId: string

      The user ID of the user (optional).

    Returns Promise<{
        bids: {
            bidderId: string;
            byCurrentUser: undefined | boolean;
            date: string;
            fanPoints: number;
        }[];
        currentHighestBid: number;
        currentUserBid: undefined | number;
        doesUserUseAutomaticBidding: boolean;
        isAuctionOpen: boolean;
        isUserHighestBidder: boolean;
        maxAutomaticBid: undefined | number;
        nextHigherBid: number;
    }>

    Throws

    RequestError if the user does not exist (unknownUserError) or if the item does not exist (unknownProductError).

getLotteryStatus

  • getLotteryStatus(rewardId, distributionPolicyId, partnerId, userId?): Promise<{
        isLotteryOpen: boolean;
        ticketsBoughtByUser: undefined | number;
        totalTicketsSold: number;
    }>

  • Returns the current status of the lottery for a lottery marketplace item.

    Parameters

    • rewardId: string

      The reward ID of the item to get the lottery status for.

    • distributionPolicyId: string

      The ID of the distribution policy of the item to get the lottery status for.

    • partnerId: string

      The partner ID of the partner offering the item to get the lottery status for.

    • OptionaluserId: string

      The user ID of the user (optional).

    Returns Promise<{
        isLotteryOpen: boolean;
        ticketsBoughtByUser: undefined | number;
        totalTicketsSold: number;
    }>

    Throws

    RequestError if the user does not exist (unknownUserError) or if the item does not exist (unknownProductError).

getMarketplaceItem

  • getMarketplaceItem(rewardId, distributionPolicyId, partnerId): Promise<{
        distributionPolicy: {
            auctionEndDate: string;
            auctionStartDate: string;
            auctionStatus: AuctionResultStatus;
            currency: Currency;
            currentHighestBid: undefined | number;
            currentNumberOfBids: undefined | number;
            distributionPolicyId: string;
            distributionType: "ShopAuctionDistributionPolicy";
            featured: boolean;
            isRecentlyAvailable: boolean;
            minBid: number;
        } | {
            currency: Currency;
            distributionPolicyId: string;
            distributionType: "ShopLotteryDistributionPolicy";
            featured: boolean;
            isRecentlyAvailable: boolean;
            lotteryEndDate: string;
            lotteryStartDate: string;
            lotteryStatus: LotteryDrawStatus;
            numTicketsToDraw: number;
            ticketPrice: number;
        } | {
            currency: Currency;
            distributionPolicyId: string;
            distributionType: "ShopPurchaseDistributionPolicy";
            featured: boolean;
            isRecentlyAvailable: boolean;
            price: number;
        };
        numAvailable: any;
        partnerId: string;
        product: {
            description: string;
            imageUrls: string[];
            partner: {
                branding: {
                    logoColorUrl: undefined | string;
                };
                name: string;
                partnerId: string;
            };
            productCategory: ProductCategory;
            rewardType: "Product";
            title: string;
        };
        readableObjectId: undefined | string;
        rewardId: string;
    }>

  • Returns the given marketplace item.

    Parameters

    • rewardId: string

      The reward ID of the item to return.

    • distributionPolicyId: string

      The ID of the distribution policy of the item to return.

    • partnerId: string

      The ID of the partner offering the item.

    Returns Promise<{
        distributionPolicy: {
            auctionEndDate: string;
            auctionStartDate: string;
            auctionStatus: AuctionResultStatus;
            currency: Currency;
            currentHighestBid: undefined | number;
            currentNumberOfBids: undefined | number;
            distributionPolicyId: string;
            distributionType: "ShopAuctionDistributionPolicy";
            featured: boolean;
            isRecentlyAvailable: boolean;
            minBid: number;
        } | {
            currency: Currency;
            distributionPolicyId: string;
            distributionType: "ShopLotteryDistributionPolicy";
            featured: boolean;
            isRecentlyAvailable: boolean;
            lotteryEndDate: string;
            lotteryStartDate: string;
            lotteryStatus: LotteryDrawStatus;
            numTicketsToDraw: number;
            ticketPrice: number;
        } | {
            currency: Currency;
            distributionPolicyId: string;
            distributionType: "ShopPurchaseDistributionPolicy";
            featured: boolean;
            isRecentlyAvailable: boolean;
            price: number;
        };
        numAvailable: any;
        partnerId: string;
        product: {
            description: string;
            imageUrls: string[];
            partner: {
                branding: {
                    logoColorUrl: undefined | string;
                };
                name: string;
                partnerId: string;
            };
            productCategory: ProductCategory;
            rewardType: "Product";
            title: string;
        };
        readableObjectId: undefined | string;
        rewardId: string;
    }>

    Throws

    RequestError if the item does not exist (unknownProductError).

getMarketplaceItems

  • getMarketplaceItems(productCategory?, limit?, lastReturnedRewardId?): Promise<{
        distributionPolicy: {
            auctionEndDate: string;
            auctionStartDate: string;
            auctionStatus: AuctionResultStatus;
            currency: Currency;
            currentHighestBid: undefined | number;
            currentNumberOfBids: undefined | number;
            distributionPolicyId: string;
            distributionType: "ShopAuctionDistributionPolicy";
            featured: boolean;
            isRecentlyAvailable: boolean;
            minBid: number;
        } | {
            currency: Currency;
            distributionPolicyId: string;
            distributionType: "ShopLotteryDistributionPolicy";
            featured: boolean;
            isRecentlyAvailable: boolean;
            lotteryEndDate: string;
            lotteryStartDate: string;
            lotteryStatus: LotteryDrawStatus;
            numTicketsToDraw: number;
            ticketPrice: number;
        } | {
            currency: Currency;
            distributionPolicyId: string;
            distributionType: "ShopPurchaseDistributionPolicy";
            featured: boolean;
            isRecentlyAvailable: boolean;
            price: number;
        };
        numAvailable: any;
        partnerId: string;
        product: {
            description: string;
            imageUrls: string[];
            partner: {
                branding: {
                    logoColorUrl: undefined | string;
                };
                name: string;
                partnerId: string;
            };
            productCategory: ProductCategory;
            rewardType: "Product";
            title: string;
        };
        readableObjectId: undefined | string;
        rewardId: string;
    }[]>

  • Returns the items listed in the marketplace of the loyalty program.

    The items can be filtered by category. Use limit and lastReturnedRewardId to paginate the results.

    Parameters

    • OptionalproductCategory: ProductCategory

      The category of the items to return. If not specified, all items will be returned.

    • Optionallimit: number

      The maximum number of items to return. If not specified, all items will be returned.

    • OptionallastReturnedRewardId: string

      The reward ID of the last returned item. If not specified, the first items will be returned.

    Returns Promise<{
        distributionPolicy: {
            auctionEndDate: string;
            auctionStartDate: string;
            auctionStatus: AuctionResultStatus;
            currency: Currency;
            currentHighestBid: undefined | number;
            currentNumberOfBids: undefined | number;
            distributionPolicyId: string;
            distributionType: "ShopAuctionDistributionPolicy";
            featured: boolean;
            isRecentlyAvailable: boolean;
            minBid: number;
        } | {
            currency: Currency;
            distributionPolicyId: string;
            distributionType: "ShopLotteryDistributionPolicy";
            featured: boolean;
            isRecentlyAvailable: boolean;
            lotteryEndDate: string;
            lotteryStartDate: string;
            lotteryStatus: LotteryDrawStatus;
            numTicketsToDraw: number;
            ticketPrice: number;
        } | {
            currency: Currency;
            distributionPolicyId: string;
            distributionType: "ShopPurchaseDistributionPolicy";
            featured: boolean;
            isRecentlyAvailable: boolean;
            price: number;
        };
        numAvailable: any;
        partnerId: string;
        product: {
            description: string;
            imageUrls: string[];
            partner: {
                branding: {
                    logoColorUrl: undefined | string;
                };
                name: string;
                partnerId: string;
            };
            productCategory: ProductCategory;
            rewardType: "Product";
            title: string;
        };
        readableObjectId: undefined | string;
        rewardId: string;
    }[]>

getObtainedProducts

  • getObtainedProducts(userId, limit?, earlierThan?): Promise<{
        deliveryDetails: {
            deliveryAddress: undefined | {
                city: string;
                country: string;
                street: string;
                zipCode: string;
            };
            deliveryName: undefined | string;
        };
        hasBeenUndone: boolean;
        product: {
            amount: number;
            deliveryDate: undefined | string;
            deliveryStatus: DeliveryStatus;
            description: string;
            imageUrls: string[];
            lotteryProductDistributionPolicyId: string;
            lotteryProductRewardId: string;
            partner: {
                branding: {
                    logoColorUrl: undefined | string;
                };
                name: string;
                partnerId: string;
            };
            productCategory: ProductCategory;
            rewardId: string;
            rewardType: "LotteryTicket";
            title: string;
        } | {
            amount: number;
            deliveryDate: undefined | string;
            deliveryStatus: DeliveryStatus;
            description: string;
            imageUrls: string[];
            partner: {
                branding: {
                    logoColorUrl: undefined | string;
                };
                name: string;
                partnerId: string;
            };
            productCategory: ProductCategory;
            rewardId: string;
            rewardType: "Product";
            title: string;
        };
        purchaseDate: string;
        transactionGroupId: string;
        transactionNr: number;
    }[]>

  • Returns the products obtained by a user. These include products bought / won in the marketplace, but also products obtained through other means like lootboxes

    Parameters

    • userId: string

      The user ID of the user.

    • Optionallimit: number

      The maximum number of items to return. If not specified, all items will be returned.

    • OptionalearlierThan: string

      A timestamp in timezone-aware ISO 8601 format. If specified, only purchases made before the given timestamp will be returned.

    Returns Promise<{
        deliveryDetails: {
            deliveryAddress: undefined | {
                city: string;
                country: string;
                street: string;
                zipCode: string;
            };
            deliveryName: undefined | string;
        };
        hasBeenUndone: boolean;
        product: {
            amount: number;
            deliveryDate: undefined | string;
            deliveryStatus: DeliveryStatus;
            description: string;
            imageUrls: string[];
            lotteryProductDistributionPolicyId: string;
            lotteryProductRewardId: string;
            partner: {
                branding: {
                    logoColorUrl: undefined | string;
                };
                name: string;
                partnerId: string;
            };
            productCategory: ProductCategory;
            rewardId: string;
            rewardType: "LotteryTicket";
            title: string;
        } | {
            amount: number;
            deliveryDate: undefined | string;
            deliveryStatus: DeliveryStatus;
            description: string;
            imageUrls: string[];
            partner: {
                branding: {
                    logoColorUrl: undefined | string;
                };
                name: string;
                partnerId: string;
            };
            productCategory: ProductCategory;
            rewardId: string;
            rewardType: "Product";
            title: string;
        };
        purchaseDate: string;
        transactionGroupId: string;
        transactionNr: number;
    }[]>

    Throws

    RequestError if the user does not exist (unknownUserError).

getUserParticipations

  • getUserParticipations(userId): Promise<{
        auctions: {
            distributionPolicy:
                | {
                    distributionType: "BasicDistributionPolicy";
                }
                | {
                    distributionType: "PromotionDistributionPolicy";
                }
                | {
                    auctionEndDate: string;
                    auctionStartDate: string;
                    auctionStatus: AuctionResultStatus;
                    currency: Currency;
                    currentHighestBid: undefined | number;
                    currentNumberOfBids: undefined | number;
                    distributionPolicyId: string;
                    distributionType: "ShopAuctionDistributionPolicy";
                    isRecentlyAvailable: boolean;
                    minBid: number;
                }
                | {
                    distributionType: "ShopLotteryDistributionPolicy";
                }
                | {
                    distributionType: "ShopPurchaseDistributionPolicy";
                };
            numAvailable: any;
            partnerId: string;
            product:
                | undefined
                | {
                    rewardType: "FanPointsReward";
                }
                | {
                    rewardType: "FanPointsVoucher";
                }
                | {
                    rewardType: "Lootbox";
                }
                | {
                    rewardType: "LotteryTicket";
                }
                | {
                    description: string;
                    imageUrls: string[];
                    partner: {
                        branding: {
                            logoColorUrl: undefined | string;
                        };
                        name: string;
                        partnerId: string;
                    };
                    productCategory: ProductCategory;
                    rewardType: "Product";
                    title: string;
                }
                | {
                    rewardType: "StatusPointsReward";
                };
            readableObjectId: undefined | string;
            rewardId: string;
        }[];
        lotteries: {
            distributionPolicy:
                | {
                    distributionType: "BasicDistributionPolicy";
                }
                | {
                    distributionType: "PromotionDistributionPolicy";
                }
                | {
                    distributionType: "ShopAuctionDistributionPolicy";
                }
                | {
                    currency: Currency;
                    distributionPolicyId: string;
                    distributionType: "ShopLotteryDistributionPolicy";
                    isRecentlyAvailable: boolean;
                    lotteryEndDate: string;
                    lotteryStartDate: string;
                    lotteryStatus: LotteryDrawStatus;
                    numTicketsToDraw: number;
                    ticketPrice: number;
                }
                | {
                    distributionType: "ShopPurchaseDistributionPolicy";
                };
            numAvailable: any;
            partnerId: string;
            product:
                | undefined
                | {
                    rewardType: "FanPointsReward";
                }
                | {
                    rewardType: "FanPointsVoucher";
                }
                | {
                    rewardType: "Lootbox";
                }
                | {
                    rewardType: "LotteryTicket";
                }
                | {
                    description: string;
                    imageUrls: string[];
                    partner: {
                        branding: {
                            logoColorUrl: undefined | string;
                        };
                        name: string;
                        partnerId: string;
                    };
                    productCategory: ProductCategory;
                    rewardType: "Product";
                    title: string;
                }
                | {
                    rewardType: "StatusPointsReward";
                };
            readableObjectId: undefined | string;
            rewardId: string;
        }[];
    }>

  • Returns the auctions and lotteries where the user is currently participating.

    Parameters

    • userId: string

      The ID of the user.

    Returns Promise<{
        auctions: {
            distributionPolicy:
                | {
                    distributionType: "BasicDistributionPolicy";
                }
                | {
                    distributionType: "PromotionDistributionPolicy";
                }
                | {
                    auctionEndDate: string;
                    auctionStartDate: string;
                    auctionStatus: AuctionResultStatus;
                    currency: Currency;
                    currentHighestBid: undefined | number;
                    currentNumberOfBids: undefined | number;
                    distributionPolicyId: string;
                    distributionType: "ShopAuctionDistributionPolicy";
                    isRecentlyAvailable: boolean;
                    minBid: number;
                }
                | {
                    distributionType: "ShopLotteryDistributionPolicy";
                }
                | {
                    distributionType: "ShopPurchaseDistributionPolicy";
                };
            numAvailable: any;
            partnerId: string;
            product:
                | undefined
                | {
                    rewardType: "FanPointsReward";
                }
                | {
                    rewardType: "FanPointsVoucher";
                }
                | {
                    rewardType: "Lootbox";
                }
                | {
                    rewardType: "LotteryTicket";
                }
                | {
                    description: string;
                    imageUrls: string[];
                    partner: {
                        branding: {
                            logoColorUrl: undefined | string;
                        };
                        name: string;
                        partnerId: string;
                    };
                    productCategory: ProductCategory;
                    rewardType: "Product";
                    title: string;
                }
                | {
                    rewardType: "StatusPointsReward";
                };
            readableObjectId: undefined | string;
            rewardId: string;
        }[];
        lotteries: {
            distributionPolicy:
                | {
                    distributionType: "BasicDistributionPolicy";
                }
                | {
                    distributionType: "PromotionDistributionPolicy";
                }
                | {
                    distributionType: "ShopAuctionDistributionPolicy";
                }
                | {
                    currency: Currency;
                    distributionPolicyId: string;
                    distributionType: "ShopLotteryDistributionPolicy";
                    isRecentlyAvailable: boolean;
                    lotteryEndDate: string;
                    lotteryStartDate: string;
                    lotteryStatus: LotteryDrawStatus;
                    numTicketsToDraw: number;
                    ticketPrice: number;
                }
                | {
                    distributionType: "ShopPurchaseDistributionPolicy";
                };
            numAvailable: any;
            partnerId: string;
            product:
                | undefined
                | {
                    rewardType: "FanPointsReward";
                }
                | {
                    rewardType: "FanPointsVoucher";
                }
                | {
                    rewardType: "Lootbox";
                }
                | {
                    rewardType: "LotteryTicket";
                }
                | {
                    description: string;
                    imageUrls: string[];
                    partner: {
                        branding: {
                            logoColorUrl: undefined | string;
                        };
                        name: string;
                        partnerId: string;
                    };
                    productCategory: ProductCategory;
                    rewardType: "Product";
                    title: string;
                }
                | {
                    rewardType: "StatusPointsReward";
                };
            readableObjectId: undefined | string;
            rewardId: string;
        }[];
    }>

    Throws

    RequestError if the user does not exist (unknownUserError).

purchaseItem

  • purchaseItem(userId, rewardId, distributionPolicyId, partnerId, amount, deliveryName, deliveryAddress): Promise<undefined>

  • Purchases a marketplace item for a user.

    Note that only marketplace items that have a distributionType of ShopPurchaseDistributionPolicy can be purchased.

    Parameters

    • userId: string

      The user ID of the user.

    • rewardId: string

      The reward ID of the item to purchase.

    • distributionPolicyId: string

      The ID of the distribution policy of the item to purchase.

    • partnerId: string

      The partner ID of the partner offering the item to purchase.

    • amount: number

      The number of the items to purchase.

    • deliveryName: string

      The name of the person to deliver the item to.

    • deliveryAddress: {
          city: string;
          country: string;
          street: string;
          zip_code: string;
      }

      The address of the person to deliver the item to.

      • city: string
      • country: string
      • street: string
      • zip_code: string

    Returns Promise<undefined>

    Throws

    RequestError if the user does not exist (unknownUserError), if the item does not exist (unknownProductError), if the user does not have enough points to purchase the item (tooFewAvailableError), or if the given amount is not valid (invalidAmountError).

purchaseLotteryTicket

  • purchaseLotteryTicket(userId, rewardId, distributionPolicyId, partnerId, amount, deliveryName, deliveryAddress): Promise<undefined>

  • Purchases a lottery ticket for a user.

    Note that only tickets for items that have a distributionType of ShopLotteryDistributionPolicy can be purchased.

    After the lottery is over, the winners will be drawn and the products will be distributed to the winners automatically.

    Parameters

    • userId: string

      The user ID of the user.

    • rewardId: string

      The reward ID of the lottery marketplace item to purchase tickets for.

    • distributionPolicyId: string

      The ID of the distribution policy of the lottery marketplace item to purchase tickets for.

    • partnerId: string

      The partner ID of the partner offering the lottery marketplace item to purchase tickets for.

    • amount: number

      The number of the tickets to purchase.

    • deliveryName: string

      The name of the person to deliver the item to.

    • deliveryAddress: {
          city: string;
          country: string;
          street: string;
          zip_code: string;
      }

      The address of the person to deliver the item to.

      • city: string
      • country: string
      • street: string
      • zip_code: string

    Returns Promise<undefined>

    Throws

    RequestError if the user does not exist (unknownUserError), if the item does not exist (unknownProductError), if the user does not have enough points to purchase the ticket (tooFewAvailableError), or if the given amount is not valid (invalidAmountError).

Settings

Member Visibility

On This Page

Methods