Offer Carousel SDK

Welcome to the Offer Carousel React Native SDK Integration Guide

This guide walks you through the process of integrating the Offer Carousel SDK into your React Native application. By using this SDK, you can easily connect to Engine by MoneyLion’s financial network, authenticate with the Engine API, and give your users access to a wide range of financial products.

The Offer Carousel SDK allows you to display a curated list of static offers across key product categories, including:

  • Earned Wage Access (EWA)

  • Credit Builder

  • Debt Relief

🔗 Interested in Personal Loan offers instead? Check out our Personal Loan SDK documentation here.

What’s Covered in This Guide

  • Software Requirements: Prerequisites for Integrating the SDK

  • Installation & Initialization: How to get started quickly

  • Customization Options: Tailor the experience to match your app’s theme and branding

  • User Experience Preview: Sample screenshots to visualize the integration (final appearance may vary based on your theme and font settings)

Carousel SDK: Example App Page
Offer Carousel SDK: Offers Wall

Setup Instructions

Step 1: Request an API Token

Before you can use the Engine SDK, you’ll need to request an API token from your Partner Manager. This subAccountToken is used to authenticate with the Engine API and provides access to different financial institutions. If you’re looking to have multiple instances of an offer carousel, leverage unique tokens per instance for distinct tracking and offer control.

Along with your unique subAccount token, you will receive a channel and zone value which is also required to define each unique instance of your SDK embed.

Optionally, your Partner Manager can generate a searchAPIToken on your behalf to enable you to control which product types appear in each offer carousel instance.

Step 2: Confirm Software Requirements

Requirements:

  • React Native version >= 0.59.0

  • Node.js >= 18

  • TypeScript (optional but recommended)

Package Size:

  • SDK Bundle Size: 1.62 MB Unpacked

Step 3: Install the SDK

Install the SDK from npm using the command using your package manager, e.g.

  • npm install @moneylion/offer-carousel

  • yarn add @moneylion/offer-carousel

👉 Refer to our NPM readme to set up and run the example app: https://www.npmjs.com/package/@moneylion/react-native-offer-carousel

Step 4: Initialize the SDK

In your app, you’ll need to initialize the SDK by rendering the Offer Carousel React component. You would need to pass in the required properties to see your entitled static offers. Refer to the “Offer Carousel SDK Properties” section below.

To implement the Offer Carousel SDK into your app, you can use the following sample code snippet. Please ensure you wrap this snippet in a self-closing `<` and `/>` tag, as demonstrated in the screenshot above.

Note: The wrapping tags have been omitted from the text below to prevent triggering a CSS attack warning on this page.

import {MoneyLionOfferCarousel} from "@moneylion/react-native-offer-carousel;
import { Text, View } from "react-native";

export default function App() {
   return (<EngineOfferCarousel
      subAccountToken={bearerToken}              
      channel={channel}      
      zone={zone}     
      searchAPIToken={bearerToken} // optional
      productType={"CreditBuilderLoan"}
      query={"Student Loan"} // overrides productType and requires "searchAPIToken" to leverage
      isDev={false} 
      fontFamily={{
	   normal: "BatonTurbo-Regular",
	   medium: "BatonTurbo-Medium",
	   bold: "BatonTurbo-Regular",
	}}
	isDarkTheme={true}
      userData={{ email: "[email protected]"}}
      showCardBorder={true}
      showDescriptionPoints={true}
      title={"Your Credit Offers"}
      subtitle={""}
      showProductTypeLabel={true}
      fallbackUI={<View> <Text>Something went wrong</Text> </View>}
      tags={"tag.traffic=home_tab&tag.medium=offers_section"}
	/*
	  * Refer to the full list of available properties and callbacks in Offer Carousel SDK Properties table.
	*/ 
   );
}

Available properties for the SDK

Property Name
Type
Required
Default
Description
Example

channel

string

Yes

-

The distribution channel identifier

"direct"

zone

string

Yes

-

The zone identifier for offer targeting

"marketplace"

subAccountToken

string

Yes

-

Unique token to fetch relevant offers

"eyJhbG..."

searchAPIToken

string

No

-

Token for the search API

"search_token_xyz"

productType

string

No

-

Specific product type to filter offers

DebtSettlement

CreditBuilderLoan

CashAdvance

EarnedWageAccess

query

string

No

-

Search query for filtering offers. Note: This Make sure to get searchAPIToken before using this prop.

"credit cards"

tags

string

No

-

Custom tags for offer filtering. Each item must be prefixed with tag.

"tag.tag1=value1&tag.tag2=value2"

fontFamily

Partial<FontFamily>

No

Fallbacks to system font

Custom font family configuration. Make sure the fonts are properly installed in your app.

{

regular: "Roboto-Regular",

medium: "Roboto-Medium",

bold: "Roboto-Bold"

}

isDev

boolean

Yes

-

Enable development mode. You can use this property to view the production offers as well, by turn it to false.

false

showCardBorder

boolean

No

false

Show a border around the offer cards

true

showDescriptionPoints

boolean

No

true

Display the offer description as bullet points

false

title

string

No

-

Custom title for the carousel

"Featured Offers"

subtitle

string

No

-

Custom subtitle for the carousel

"Personalized for you"

isDarkTheme

boolean

No

false

Enable dark theme mode.

true

showProductTypeLabel

boolean

No

false

Whether to display product type labels

true

fallbackUI

React.ReactNode

No

-

Custom UI to show on error

<ErrorComponent />

userData

{ email?: string }

No

-

User data for offer personalization

The Engine Offer Carousel SDK has multiple real-time Event Handlers so you can track activity in the SDK in real time.

Event Property
Type
Required
Description
Example

onError

(error: CustomError) => void CustomError {

code?: number;

message: string;

timestamp: string;

}

No

Called when an error occurs.

{ code: 500,

message: “Configuration request failed with status: 500",

timestamp:”2025-07-24T10:12:02.492Z" }

onLoad

(numOffers: number) => void

No

Called when offers are loaded. Make sure to use the callback value to show the appropriate UI.

(count) => console.log(${count} offers loaded)

onInitialize

(props: onInitializeProps) => void onInitializeProps { timestamp: string; }

No

Called when the SDK is initialized.

(props) => console.log(props)

onRateTableSubmit

(props: onRateTableSubmitProps) => void

onRateTableSubmitProps { timestamp: string;

productTypes: string[];

resultType: ResultType;

defaultProductType: string; }

No

Called when a rate table submission is made.

(props) => console.log(props)

onRateTableResponse

(props: onRateTableResponseProps) => void onRateTableResponseProps { timestamp: string;

isError: boolean;

offers: BaseOffer[];

rateTableUuid: string;

leadUuid: string; }

No

Called when a response for a rate table is received.

(props) => console.log(props)

onOfferDisplayInViewport

(props: onOfferDisplayInViewportProps) => void onOfferDisplayInViewportProps {

timestamp: string;

offerUuid: string;

rateTableUuid: string;

leadUuid: string;

offer: BaseOffer;

offerIndex: number;

context: "horizontal_scroll" | "vertical_scroll";

}

No

Called when an offer is displayed in the viewport.

(props) => console.log(props)

onOfferClick

(props: onOfferClickProps) => void

onOfferClickProps {

timestamp: string;

offerUuid: string;

rateTableUuid: string;

leadUuid: string;

offer: BaseOffer;

offerIndex: number;

context: "horizontal_scroll" | "vertical_scroll" | "offer_details";

}

No

Called when an offer is clicked.

(props) => console.log(props)

onOfferDetailsPageOpen

(props: onOfferDetailsPageOpenProps) => void

onOfferDetailsPageOpenProps {

timestamp: string;

offerUuid: string;

rateTableUuid: string;

leadUuid: string;

offer: BaseOffer;

offerIndex: number;

context: "horizontal_scroll" | "vertical_scroll";

}

No

Called when the offer details page is opened.

(props) => console.log(props)

onOfferDetailsPageClose

(props: onOfferDetailsPageCloseProps) => void

onOfferDetailsPageCloseProps {

timestamp: string;

offerUuid: string;

rateTableUuid: string;

leadUuid: string;

offer: BaseOffer;

offerIndex: number;

}

No

Called when the offer details page is closed.

(props) => console.log(props)

Error Handling

The SDK provides a comprehensive onError callback to manage various issues. This callback is invoked for configuration errors, server errors, network errors, and potential UI errors.

For configuration and server errors, the onError callback returns a code representing the HTTP error response, along with a descriptive error message.

Example

{
   code: 500,
   message: “Configuration request failed with status: 500",
   timestamp:”2025-07-24T10:12:02.492Z"
}

To provide a fallback UI in case of failure, you can utilize the fallbackUI property to pass in a custom React component. Note that this will only show when there’s some error in rendering logic. API errors should be handled by the onError callback.

UI Customizations

SDK Brands

We manage branding for your Offer Carousel SDK by creating a unique brand for each partner, applied consistently across all carousels. The brand's color palette defines its visual style, with theme colors generated to match and establish the application's overall look and feel.

  • Color Palette: A Brand's Palette defines the colors and style used in our experiences.

    • Note: any colors not defined will be generated such that they align with the colors provided.

  • Theme Colors: The theme colors are used to define the look and feel of the application. The colors can be generated using the colors provided in the color palette above.

SDK Properties

The SDK provides the following properties to customize the appearance of the component:

isDarkTheme

By setting this property, you can configure the SDK to match your app’s theme.

Example Offer Carousel with isDarkTheme set to true

showProductTypeLabel:

This property controls the visibility of the offer type on top of the offer card.

Example Offer Carousel with showProductTypeLabel set to true for offers with type “Income Opportunities”

showCardBorder:

Improve visibility of the offer cards by making them more distinct from the background. This is particularly useful when the container's background color is similar to the offer card's background color.

With showCardBorder set to false
With showCardBorder set to true

fontFamily:

This property updates the fonts used by the offer carousel. By default, the SDK will use system fonts.

Example offer with Montserrat font
Example offer with Baton Turbo font

Additional Customization & Functionality

Offer Enablements (Minimums & Maximums)

To ensure a smooth and consistent user experience, the Offer Carousel SDK enforces the following rules:

  • Minimum Requirement: At least one offer must be available for the carousel to be displayed. If no offers are returned, the carousel will not render.

  • Maximum Limit: There is no upper limit to the number of offers the SDK can display.

Custom Audiences

Custom Audiences enable precise targeting for select Earned Wage Access (EWA) and Credit Builder offers, driving higher engagement and conversion rates. By reaching only the most relevant users, partners benefit from improved performance, increased offer volume from supply partners, and accelerated acquisition growth.

Key features include:

  • Suppression: Preventing existing Empower customers from seeing duplicate offers, reducing fatigue and improving the user experience. We support suppression for select offers from these partners:

    • EWA: Empower, Current, Chime, EarnIn

    • Credit Builders: CreditStrong

  • Coming Soon – Remarketing: Re-engage churned customers with targeted offers at a lower payout, boosting retention and maximizing customer value.

Fonts and Colors

To maintain brand consistency within your app experience, the Offer Carousel SDK supports font and color customization with the following requirements:

Fonts:

  • Any custom fonts must be pre-installed in the host application (ie the partner’s app).

    • For example, if Partner ABC wants to use a custom font, that font must already be supported and linked within their hosted app.

    • The SDK will reference fonts by name via the fontFamily property.

Colors:

  • The SDK supports the full range of hex color codes, consistent with what’s supported in the Payload platform across partner pages, embeds, and SDKs.

    • Ideally, partners should use an existing brand configuration (if one has been set up previously).

    • Alternatively, partners can provide their preferred hex codes, and we will apply them during setup.This includes all standard 16 million+ hex color values, like those found in this HTML color picker.

Last updated

Was this helpful?