Virtual currency FAQ docs section (#1028)

* introduces 2 faq docs and some minor doc updates

* typos

* incorporate feedback

* feedback and minor updates

* update sidebar text

* minor update

Author: tiinanguyen

docs/offerings/virtual-currency.mdx

@@ -234,23 +234,6 @@ Virtual currency adjustments made through the [API](/offerings/virtual-currency#
 
 For more information about virtual currency events, including customer timeline events and webhook events, see our [Virtual Currency Events](/offerings/virtual-currency/events) documentation.
 
-### RevenueCat's Firebase Extension integration
-
-If you have the [Firebase Extension integration](/integrations/third-party-integrations/firebase-integration#4-send-customer-information-to-firestore) enabled, RevenueCat will include the customer's virtual currency balance in the dispatched events' payload. Balance changes due to other reasons, such as manual adjustments through our Developer API endpoints **will not** trigger an event.
-
-When an event is dispatched, the Firebase Extension event payload will include a `virtual_currencies` object containing the customer's **total balance** for each currency after the purchase. The below example shows the customer's total balance for "GLD" is 80, while "SLV" is 40.
-
-import firebaseExtensionPayload from "@site/code_blocks/virtual-currency/firebase-balance.json?raw";
-
-<RCCodeBlock
-  tabs={[
-    {
-      type: "json",
-      content: firebaseExtensionPayload,
-    },
-  ]}
-/>
-
 ## Best practices and security considerations
 
 Virtual currencies is a very powerful feature that RevenueCat provides, however it needs to be used correctly to ensure high standards of security. Here are some necessary requirements in order to make sure that bad actors cannot exploit your system for their benefit or to harm other users of your app.

docs/offerings/virtual-currency/events.mdx

@@ -121,6 +121,23 @@ Example of a multi-currency transaction:
 - **Fraud Detection**: Monitor for unusual patterns in virtual currency transactions
 - **Customer Support**: Use timeline events to help customers understand their transaction history
 
+## RevenueCat's Firebase Extension integration
+
+If you have the [Firebase Extension integration](/integrations/third-party-integrations/firebase-integration#4-send-customer-information-to-firestore) enabled, RevenueCat will include the customer's virtual currency balance in the dispatched events' payload. Balance changes due to other reasons, such as manual adjustments through our Developer API endpoints **will not** trigger an event.
+
+When an event is dispatched, the Firebase Extension event payload will include a `virtual_currencies` object containing the customer's **total balance** for each currency after the purchase. The below example shows the customer's total balance for "GLD" is 80, while "SLV" is 40.
+
+import firebaseExtensionPayload from "@site/code_blocks/virtual-currency/firebase-balance.json?raw";
+
+<RCCodeBlock
+  tabs={[
+    {
+      type: "json",
+      content: firebaseExtensionPayload,
+    },
+  ]}
+/>
+
 ## Next Steps
 
 - [Webhook Event Types and Fields](/integrations/webhooks/event-types-and-fields#virtual-currency-transaction-fields)

docs/offerings/virtual-currency/faq/balance-source-of-truth.mdx

@@ -0,0 +1,123 @@
+---
+title: Balance Source of Truth
+sidebar_label: Balance Source of Truth
+slug: balance-source-of-truth
+hidden: false
+---
+
+When implementing virtual currencies in your app, an important architectural decision is choosing where the source of truth for the customer's balance should be maintained.
+
+There are two common approaches:
+
+- RevenueCat as the source of truth
+- Your backend as the source of truth
+
+Which path you choose depends on your starting point and existing infrastructure.
+
+## Approach 1: RevenueCat as Source of Truth (Recommended for New Setups)
+
+RevenueCat is designed to be the **single source of truth** for virtual currency balances and transaction history. If you're implementing virtual currencies for the first time (no existing balance logic or storage), we recommend using RevenueCat as the system of record.
+
+With this approach:
+
+- RevenueCat tracks balances
+- Currencies are granted automatically after successful purchases
+- RevenueCat validates and deducts currencies during spend operations
+- Your app can fetch the current balance via the SDK
+
+### How It Works
+
+The following diagrams walk through the flow of a check balance, purchase, and spend where RevenueCat manages the balance.
+
+![](/docs_images/virtual-currency/VC_RC_FLOW_CHECK_BALANCE.png)
+
+#### 🔹 Balance Check Flow
+
+1. The customer opens the app
+2. The app calls `.virtualCurrencies()` to fetch the customer's balance. For code samples see our [docs](/offerings/virtual-currency#from-the-sdk)
+3. RevenueCat responds with the balance
+4. The app displays the balance
+
+:::warning
+The balance is cached. You should call `invalidateVirtualCurrenciesCache()` before fetching again if you want fresh data (e.g. after a purchase or spend).
+:::
+
+![](/docs_images/virtual-currency/VC_RC_FLOW_PURCHASE.png)
+
+#### 🔹 Purchase Flow (Buy Coins)
+
+1. The customer taps “Buy 100 Coins”
+2. The app calls purchase(product) via RevenueCat
+3. RevenueCat validates the transaction with the Store
+4. RevenueCat grants the coins automatically and updates the balance server-side
+5. The app can re-fetch the balance and display the new amount
+
+:::success
+RevenueCat tracks the balance and grants coins directly. No backend logic is needed for purchases.
+:::
+
+![](/docs_images/virtual-currency/VC_RC_FLOW_SPEND.png)
+
+#### 🔹 Spend Flow (Use Coins)
+
+1. The customer tries to spend 10 coins
+2. The app notifies your backend to spend the coins, which would call RevenueCat via a [`POST /virtual_currencies/transactions`](https://www.revenuecat.com/docs/api-v2#tag/Customer/operation/create-virtual-currencies-transaction) request
+3. RevenueCat checks if the customer has sufficient balance and, if so, subtracts the amount
+4. RevenueCat will notify your backend the request was successful
+5. The app fetches the new balance (remember to invalidate cache)
+6. The app grants what the coins unlocked
+
+:::info
+Your backend is only responsible for interpreting what the 10 coins should unlock. RevenueCat handles validation and deduction.
+:::
+
+## Approach 2: Your Backend as Source of Truth
+
+If you've already implemented a virtual currency system on your backend (e.g: for web), it likely makes sense to continue treating your backend as the source of truth and rely on RevenueCat webhooks to update balances when purchases are made or when subscription lifecycle changes.
+
+In this model:
+
+- RevenueCat handles purchase validation and emits `VIRTUAL_CURRENCY_TRANSACTION` webhooks
+- Your backend listens for these webhooks and updates the customer's balance
+- Your app fetches balances directly from your backend
+- Spending is initiated from the app → your backend, which performs balance validation and deducts currency accordingly
+
+This approach allows you to keep centralized control of balances, while leveraging RevenueCat’s virtual currency logic to determine the correct amount of currency to grant for each purchase.
+
+### How It Works
+
+This diagrams illustrate how your backend listens to RevenueCat webhooks and handles balance management.
+
+![](/docs_images/virtual-currency/VC_BACKEND_FLOW_CHECK_BALANCE.png)
+
+#### 🔹 Balance Check Flow
+
+1. The customer wants to see their balance
+2. The app requests the balance from your backend
+3. The backend responds with the current balance
+4. The app displays the balance to the customer
+
+![](/docs_images/virtual-currency/VC_BACKEND_FLOW_PURCHASE.png)
+
+#### 🔹 Purchase Flow (Buy Coins)
+
+1. The customer initiates a purchase in the app
+2. The app uses the RevenueCat SDK to call purchase(product)
+3. RevenueCat validates the transaction with the Store
+4. Once verified, RevenueCat emits a [`VIRTUAL_CURRENCY_TRANSACTION` webhook](/offerings/virtual-currency/events#webhook-events)
+5. Your backend receives this webhook and updates the customer's balance accordingly
+6. The app can then fetch and display the updated balance
+
+:::info
+RevenueCat tracks the amount of virtual currency granted from purchases and subscriptions. As a result, the balance shown in RevenueCat may get out of sync with your system if spending occurs outside of RevenueCat.
+:::
+
+![](/docs_images/virtual-currency/VC_BACKEND_FLOW_SPEND.png)
+
+#### 🔹 Spend Flow (Use Coins)
+
+1. The customer chooses to spend 10 coins in the app
+2. The app sends a message to your backend: “Spend 10 coins”
+3. Your backend contains the business logic to determine what the coins unlock (e.g., an item or feature)
+4. Your backend checks if the customer has enough balance, and if so, deducts the amount and returns a success response
+5. The app updates the UI and shows what was unlocked

docs/offerings/virtual-currency/faq/virtual-items.mdx

@@ -0,0 +1,77 @@
+---
+title: Virtual Items
+sidebar_label: Virtual Items
+slug: virtual-items
+hidden: true
+---
+
+RevenueCat’s Virtual Currency feature is designed to help you track and manage balances of in-app currencies, such as coins, tokens, or minutes granted via purchases. While we don’t natively support managing "virtual items" (e.g., consumable items like tickets, skins, or passes that are bought using virtual currency), it’s possible to work around this limitation using a creative implementation of multiple virtual currencies.
+
+This guide walks you through how to implement this pattern.
+
+## Treat Items as Virtual Currencies
+
+If your app has a **small and fixed set of virtual items**, you can represent each item as its own virtual currency.
+
+:::warning 100 virtual currency limit
+RevenueCat has a limit of 100 virtual currencies per project that can be configured.
+:::
+
+Example scenario:
+You want to sell:
+
+- Tickets (cost: 2 coins)
+- Passes (cost: 5 coins)
+
+Set up the following virtual currencies in RevenueCat:
+
+- `Coins`: Your primary currency
+- `Tickets`: Treated as a currency, but really represents an owned item
+- `Passes`: Same as above
+
+## Purchasing a Virtual Item
+
+### 1. Customer Initiates Item Purchase
+
+![](/docs_images/virtual-currency/VIRTUAL_ITEMS_PURCHASE.png)
+
+The customer decides to buy a virtual item (e.g., a ticket) using their coins.
+
+- **Action:** Customer taps "Buy Ticket (2 coins)" in the app.
+- **App → Your backend request:**
+  ```http
+  POST /api/purchase-ticket
+  Content-Type: application/json
+  {
+    "app_user_id": "app_user_id",
+    "item": "ticket"
+  }
+  ```
+
+### 2. Your Backend Contacts RevenueCat API
+
+![](/docs_images/virtual-currency/VIRTUAL_ITEMS_BACKEND_TO_RC.png)
+
+- **API Request to RevenueCat:**
+  ```http
+  curl --location 'https://api.revenuecat.com/v2/projects/<YOUR_PROJECT_ID>/customers/<YOUR_CUSTOMER_ID>/virtual_currencies/transactions' \
+  --header 'Content-Type: application/json' \
+  --header 'Authorization: Bearer sk_***************************' \
+  --data '{
+      "adjustments": {
+          "Coins": -2,
+          "Tickets": +1
+      }
+  }'
+  ```
+- **Validation:** RevenueCat checks that the customer has enough coins and that the transaction is atomic (both succeed or both fail).
+
+### 3. Your App Processes Result
+
+![](/docs_images/virtual-currency/VIRTUAL_ITEMS_APP.png)
+
+- On success:
+  - After any purchases or spends, make sure to invalidate the virtual currencies cache through `invalidateVirtualCurrenciesCache()`
+  - Call RevenueCat's `.virtualCurrencies()` SDK method to fetch the updated balance. In this scenario, the updated balance will contain the coin's balance of 8 and ticket's balance of 1
+- On failure:
+  - This means the customer did not have enough balance to perform the transaction. You should show them a paywall to top-up and/or show an insufficient balance message

sidebars.ts

@@ -321,6 +321,17 @@ const offeringsCategory = Category({
         Page({ slug: "subscriptions" }),
         Page({ slug: "refunds" }),
         Page({ slug: "events" }),
+        SubCategory({
+          label: "Virtual Currency FAQs",
+          itemsPathPrefix: "faq/",
+          items: [Page({ slug: "balance-source-of-truth" })],
+          index: {
+            title: "Virtual Currency FAQs",
+            link: "/faq",
+            description:
+              "Additional guidance for the Virtual Currency feature.",
+          },
+        }),
       ],
     }),
     Page({ slug: "offerings/troubleshooting" }),