Skip to main content

Virtual Currency Events

RevenueCat provides event tracking for virtual currency transactions, allowing you to monitor and respond to balance changes in real-time through webhooks.

📘Adjustments via API are view-only

Virtual currency adjustments made through the API 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 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.

Event Types​

The following virtual currency events can appear in the customer timeline:

Event NameDescriptionWebhook Event
Granted ... [Currency]Currency was added to the customer's balanceVIRTUAL_CURRENCY_TRANSACTION
Spent ... [Currency]Currency was removed from the customer's balanceVIRTUAL_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 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:

{
    "event": {
      "adjustments": [
        {
          "amount": 100,
          "currency": {
            "code": "CRD",
            "description": "The main currency unit",
            "name": "Credits"
          }
        }
      ],
      "aliases": [
        "$RCAnonymousID:8069238d6049ce87cc529853916d624c"
      ],
      "app_id": "1234567890",
      "app_user_id": "1234567890",
      "country_code": "US",
      "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​

FieldTypeDescriptionPossible Values
adjustmentsArrayArray of virtual currency adjustments made in this transaction. Each adjustment contains the amount and currency details.
adjustments[].amountIntegerThe amount of virtual currency added (positive) or removed (negative) from the customer's balance.
adjustments[].currencyObjectDetails about the virtual currency involved in the transaction.
adjustments[].currency.codeStringThe unique identifier for the virtual currency.
adjustments[].currency.nameStringThe display name of the virtual currency.
adjustments[].currency.descriptionStringThe description of the virtual currency.
product_display_nameStringThe display name of the product that triggered the virtual currency transaction.
purchase_environmentStringThe environment where the product purchase was made.SANDBOX, PRODUCTION.
sourceStringThe source of the virtual currency transaction.in_app_purchase, admin_api
virtual_currency_transaction_idStringUnique 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:

{
  "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

Next Steps​