--- id: "offerings/virtual-currency/events" title: "Virtual Currency Events" description: "RevenueCat provides event tracking for virtual currency transactions, allowing you to monitor and respond to balance changes in real-time through webhooks." permalink: "/docs/offerings/virtual-currency/events" slug: "events" version: "current" original_source: "docs/offerings/virtual-currency/events.mdx" --- > **AI agents:** This is the Markdown version of a RevenueCat documentation page. For the complete documentation index, see [llms.txt](https://www.revenuecat.com/docs/llms.txt). RevenueCat provides event tracking for virtual currency transactions, allowing you to monitor and respond to balance changes in real-time through webhooks. :::info\[Adjustments via API are view-only] Virtual currency adjustments made through the [API](https://www.revenuecat.com/docs/offerings/virtual-currency#depositing-or-spending) will appear in the customer timeline, but cannot be clicked for additional details. These adjustments are displayed for reference only and do not generate webhook events. ::: ## Timeline Events Virtual currency transactions appear in the [Customer History](https://www.revenuecat.com/docs/dashboard-and-metrics/customer-profile) timeline, providing visibility into when currency was granted or spent from a customer's balance. These events help with debugging, customer support, and understanding customer behavior. ![](https://www.revenuecat.com/docs_images/virtual-currency/vc-customer-history-timeline.png) ### Event Types The following virtual currency events can appear in the customer timeline: | Event Name | Description | Webhook Event | | ---------------------- | ------------------------------------------------ | ------------------------------ | | Granted ... \[Currency] | Currency was added to the customer's balance | `VIRTUAL_CURRENCY_TRANSACTION` | | Spent ... \[Currency] | Currency was removed from the customer's balance | `VIRTUAL_CURRENCY_TRANSACTION` | ### Event Details When you click on a virtual currency event in the Customer History, you can view additional details including: - The amount of currency granted or spent - The currency type and metadata - The product that triggered the transaction - The [source](https://www.revenuecat.com/docs/offerings/virtual-currency/events#source-values) of the transaction (`in_app_purchase`, `admin_api`) ## Webhook Events RevenueCat sends `VIRTUAL_CURRENCY_TRANSACTION` webhook events whenever a virtual currency transaction occurs. These events provide detailed information about the transaction, including the amount, currency type, and source of the transaction. ### When Events Are Sent Virtual currency webhook events are triggered in the following scenarios: - **In-app purchases**: When a customer purchases a product associated with virtual currency - **Subscription lifecycle**: For subscriptions that grant virtual currency, events are sent for the entire subscription lifecycle (initial purchase, renewals, refunds, etc.) whenever there is an adjustment to be made to the currency balance - **Manual adjustments via dashboard**: When virtual currency is manually adjusted through the dashboard ### Event Structure Virtual currency webhook events include standard webhook fields plus virtual currency-specific fields. Here's an example of a virtual currency transaction event: ```json { "event": { "adjustments": [ { "amount": 100, "currency": { "code": "CRD", "description": "The main currency unit", "name": "Credits" } } ], "aliases": [ "$RCAnonymousID:8069238d6049ce87cc529853916d624c" ], "app_id": "1234567890", "app_user_id": "1234567890", "event_timestamp_ms": 1658726378679, "product_display_name": "Monthly sub for 100 credits", "product_id": "1M_100credits", "purchase_environment": "PRODUCTION", "source": "in_app_purchase", "store": "APP_STORE", "subscriber_attributes": { "$email": { "updated_at_ms": 1662955084635, "value": "firstlast@gmail.com" } }, "transaction_id": "123456789012345", "virtual_currency_transaction_id": "vatx123456789012345", "type": "VIRTUAL_CURRENCY_TRANSACTION", "id": "12345678-1234-1234-1234-123456789012" }, "api_version": "1.0" } ``` ### Virtual Currency Specific Fields | Field | Type | Description | Possible Values | | ------------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------- | ------------------------------ | | `adjustments` | Array | Array of virtual currency adjustments made in this transaction. Each adjustment contains the amount and currency details. | | | `adjustments[].amount` | Integer | The amount of virtual currency added (positive) or removed (negative) from the customer's balance. | | | `adjustments[].currency` | Object | Details about the virtual currency involved in the transaction. | | | `adjustments[].currency.code` | String | The unique identifier for the virtual currency. | | | `adjustments[].currency.name` | String | The display name of the virtual currency. | | | `adjustments[].currency.description` | String | The description of the virtual currency. | | | `product_display_name` | String | The display name of the product that triggered the virtual currency transaction. | | | `purchase_environment` | String | The environment where the product purchase was made. | `SANDBOX`, `PRODUCTION`. | | `source` | String | The source of the virtual currency transaction. | `in_app_purchase`, `admin_api` | | `virtual_currency_transaction_id` | String | Unique identifier for this virtual currency transaction. | | ### Source Values The `source` field indicates what triggered the virtual currency balance adjustment: - `in_app_purchase`: Currency granted from a one-time or subscription purchase. This also includes the subscription lifecycle (initial purchase, renewals, refunds, etc.) whenever there is an adjustment to be made to the currency balance - `admin_api`: Currency was manually adjusted through the dashboard ### Multiple Currency Adjustments A single webhook event can include adjustments for multiple virtual currency types. This is useful for scenarios like currency conversion or when a single purchase grants multiple types of currency. Example of a multi-currency transaction: ```json { "adjustments": [ { "amount": 1000, "currency": { "code": "GLD", "name": "Gold", "description": "Premium currency" } }, { "amount": 50, "currency": { "code": "SLV", "name": "Silver", "description": "Standard currency" } } ] } ``` ## Best Practices ### Monitoring - **Balance Reconciliation**: Use webhook events to reconcile virtual currency balances with your internal systems - **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](https://www.revenuecat.com/docs/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. ```json { "virtual_currencies": { "GLD": { "balance": 80 }, "SLV": { "balance": 40 } } } ``` ## Next Steps - [Webhook Event Types and Fields](https://www.revenuecat.com/docs/integrations/webhooks/event-types-and-fields#virtual-currency-transaction-fields) - [Customer History](https://www.revenuecat.com/docs/dashboard-and-metrics/customer-profile) - [Virtual Currency Subscriptions](https://www.revenuecat.com/docs/offerings/virtual-currency/subscriptions) - [Virtual Currency Refunds](https://www.revenuecat.com/docs/offerings/virtual-currency/refunds)