BuyCreditsModal Documentation

Overview

The BuyCreditsModal component is an essential part of the Vantage analytics and data platform. Its primary purpose is to facilitate the purchase of credits (tokens) by users, enabling them to access various features within the platform. The modal provides a two-step purchasing flow:

1. Tier Selection: Users can select a specific pricing tier for tokens.
2. Stripe Embedded Checkout: Once a tier is selected, the user is taken through an embedded Stripe checkout process to complete the transaction.

Upon successful payment, the tokens are immediately credited to the user's account.

Settings

The BuyCreditsModal accepts several props that control its behavior and appearance. Below is a comprehensive list of each setting:

1. open

• Input Type: Boolean
• Description: Controls the visibility of the modal. When set to true, the modal is displayed; when false, it is hidden.
• Default Value: false
• Impact: If not set to true, the modal will not render.

2. onClose

• Input Type: Function
• Description: Callback function that is executed when the modal is requested to close. This can be used to reset application states or trigger other UI changes.
• Default Value: None
• Impact: Important for opening and closing the modal correctly and managing user actions effectively.

3. tiers

• Input Type: Array of Objects
• Description: An array containing the different pricing tiers available for purchase. Each object should have properties { price, priceId, tokens } where:
  • price (number): Amount to be charged for the selected tier.
  • priceId (string): Identifier for the specific tier used in payment processing.
  • tokens (number): The number of tokens that will be credited upon purchase.
• Default Value: [] (an empty array)
• Impact: Affects the available options in the modal for the user to select from. Without tiers, the modal cannot function correctly.

4. clientId

• Input Type: String
• Description: Unique identifier for the current user or client making the purchase. This is essential for linking the purchase to the correct account during the fulfillment process.
• Default Value: None
• Impact: Required for API calls to authenticate and associate the purchase with the user.

5. onPurchase

• Input Type: Function (optional)
• Description: A callback function that is called after a successful purchase. This can be leveraged to trigger additional actions, such as notifications or UI updates.
• Default Value: None
• Impact: Enhances the interactivity and responsiveness of the application by allowing further actions after payment confirmation.

6. message

• Input Type: String (optional)
• Description: Custom message displayed in the modal that describes the purpose of purchasing tokens. This can be used to override the default message if needed.
• Default Value: undefined
• Impact: If provided, it personalizes the user experience by adding specific contextual information relevant to the user or action.

Functionality

• Automatic Tier Selection: The component automatically selects the first available tier if the modal is opened and no tier is actively selected.
• Error Handling: If an error occurs during the transaction, it captures and displays error messages to inform users of potential issues.
• Payment Flow: It orchestrates a two-step flow that involves selecting a tier and then proceeding to payment through Stripe, ensuring seamless transaction handling.
• Success Notification: Upon successful payment, tokens are either immediately added to the user's balance, and a success message is displayed.

Data Expectations

The BuyCreditsModal expects certain data constructs:

• The tiers prop should be an array of objects with the following structure:

[
  {
    "price": 10.0,
    "priceId": "tier_123456",
    "tokens": 100
  },
  {
    "price": 25.0,
    "priceId": "tier_789012",
    "tokens": 300
  }
]

• The clientId should be a valid string corresponding to the logged-in user's ID.

Use Cases & Examples

Use Case 1: Token Purchase for Usage Tracking

A company utilizes Vantage to track user interactions within their application. They require users to purchase tokens to access premium analytical features.

Use Case 2: Dynamic Pricing Adjustments

A marketing team wants to run a promotion where they offer discounted token tiers for a limited time.

Example Configuration

To implement Use Case 1, the BuyCreditsModal could be configured as follows to set pricing tiers and proper callbacks:

const tiers = [
    { price: 10.00, priceId: "tier_001", tokens: 100 },
    { price: 20.00, priceId: "tier_002", tokens: 250 },
    { price: 50.00, priceId: "tier_003", tokens: 600 }
];

<BuyCreditsModal
    open={true}
    onClose={() => console.log('Modal closed')}
    tiers={tiers}
    clientId={"client_abc_123"}
    onPurchase={() => console.log('Purchase successful!')}
    message="Purchase tokens to unlock premium features."
/>

This configuration would create a modal where users can choose between different tiers of token purchases, each associated with the necessary payment processing details.