Skip to content

Commit 5e9c998

Browse files
tiinanguyentiinanguyen
authored
Virtual currency event docs (#951)
* initial draft for vc events doc * fixing typo * add details about API events * address feedback * update header * minor updates * updating some wording
1 parent 06c2b04 commit 5e9c998

File tree

8 files changed

+279
-60
lines changed

8 files changed

+279
-60
lines changed

‎code_blocks/integrations/webhooks/sample-events_15.json

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
{
2+
"event": {
3+
"adjustments": [
4+
{
5+
"amount": 100,
6+
"currency": {
7+
"code": "CRD",
8+
"description": "The main currency unit",
9+
"name": "Credits"
10+
}
11+
}
12+
],
13+
"aliases": [
14+
"$RCAnonymousID:8069238d6049ce87cc529853916d624c"
15+
],
16+
"app_id": "1234567890",
17+
"app_user_id": "1234567890",
18+
"country_code": "US",
19+
"event_timestamp_ms": 1658726378679,
20+
"product_display_name": "Monthly sub for 100 credits",
21+
"product_id": "1M_100credits",
22+
"purchase_environment": "PRODUCTION",
23+
"source": "in_app_purchase",
24+
"store": "APP_STORE",
25+
"subscriber_attributes": {
26+
"$email": {
27+
"updated_at_ms": 1662955084635,
28+
"value": "[email protected]"
29+
}
30+
},
31+
"transaction_id": "123456789012345",
32+
"virtual_currency_transaction_id": "vatx123456789012345",
33+
"type": "VIRTUAL_CURRENCY_TRANSACTION",
34+
"id": "12345678-1234-1234-1234-123456789012"
35+
},
36+
"api_version": "1.0"
37+
}

‎docs/dashboard-and-metrics/customer-history.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,8 @@ Below is a table with all the event types you can expect in the customer history
3636
| Created a new alias | Was aliased with another App User Id. | `SUBSCRIBER_ALIAS` (deprecated) |
3737
| Was granted the ... Entitlement | Was granted an entitlement directly from the RevenueCat dashboard or API | `NON_RENEWING_PURCHASE` |
3838
| Had their granted Entitlement removed | A previously granted entitlement was removed from the RevenueCat dashboard or API | `CANCELLATION` |
39+
| Granted ... [Currency] | Virtual currency was added to the customer's balance through a purchase or subscription | `VIRTUAL_CURRENCY_TRANSACTION` |
40+
| Spent ... [Currency] | Virtual currency was removed from the customer's balance | `VIRTUAL_CURRENCY_TRANSACTION` |
3941

4042
:::info Missing or incorrect prices
4143
It is possible for prices to be missing or incorrect, especially for apps that have migrated from a different system to RevenueCat. The stores provide very minimal pricing information for developers, so RevenueCat estimates the transaction price based off the data that is available - if you have old products that are no longer available for sale or changed the price of your products before using RevenueCat, you can expect some prices to be missing or incorrect. We do our best to backfill prices over time if more up-to-date information becomes available.

‎docs/integrations/webhooks/event-types-and-fields.mdx

Lines changed: 76 additions & 58 deletions
Large diffs are not rendered by default.

‎docs/integrations/webhooks/sample-events.mdx

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -92,3 +92,17 @@ import temporaryEntitlementGrantContent from "@site/code_blocks/integrations/web
9292
},
9393
]}
9494
/>
95+
96+
When a virtual currency transaction occurs, a VIRTUAL_CURRENCY_TRANSACTION webhook is created:
97+
98+
import virtualCurrencyTransactionContent from "@site/code_blocks/integrations/webhooks/sample-events_15.json?raw";
99+
100+
<RCCodeBlock
101+
tabs={[
102+
{
103+
type: "json",
104+
content: virtualCurrencyTransactionContent,
105+
name: "Virtual Currency Transaction",
106+
},
107+
]}
108+
/>

‎docs/offerings/virtual-currency.mdx

Lines changed: 14 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -155,6 +155,7 @@ import content5 from "@site/code_blocks/virtual-currency/balance-response.json?r
155155
#### From the SDK
156156

157157
##### iOS
158+
158159
import fetchVCBalancesSwift from "@site/code_blocks/virtual-currency/vc-balance-sdk-ios.swift?raw";
159160

160161
<RCCodeBlock
@@ -253,7 +254,19 @@ import content3 from "@site/code_blocks/virtual-currency/transaction-adjustment.
253254
]}
254255
/>
255256

256-
## RevenueCat's Firebase Extension integration
257+
## Events
258+
259+
RevenueCat provides event tracking for virtual currency transactions, allowing you to monitor and respond to balance changes in real-time through webhooks.
260+
261+
Virtual currency transactions appear in the [Customer History](/dashboard-and-metrics/customer-history) timeline and trigger `VIRTUAL_CURRENCY_TRANSACTION` webhook events for the entire subscription lifecycle whenever there are currency balance adjustments.
262+
263+
:::info Adjustments via API are view-only
264+
Virtual currency adjustments made through the [API](/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.
265+
:::
266+
267+
For more information about virtual currency events, including customer timeline events and webhook events, see our [Virtual Currency Events](/offerings/virtual-currency/events) documentation.
268+
269+
### RevenueCat's Firebase Extension integration
257270

258271
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.
259272

‎docs/offerings/virtual-currency/events.mdx

Lines changed: 131 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,131 @@
1+
---
2+
title: Virtual Currency Events
3+
sidebar_label: Events
4+
slug: events
5+
hidden: false
6+
---
7+
8+
# Virtual Currency Events
9+
10+
RevenueCat provides event tracking for virtual currency transactions, allowing you to monitor and respond to balance changes in real-time through webhooks.
11+
12+
:::info Adjustments via API are view-only
13+
Virtual currency adjustments made through the [API](/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.
14+
:::
15+
16+
## Timeline Events
17+
18+
Virtual currency transactions appear in the [Customer History](/dashboard-and-metrics/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.
19+
20+
![](/docs_images/virtual-currency/vc-customer-history-timeline.png)
21+
22+
### Event Types
23+
24+
The following virtual currency events can appear in the customer timeline:
25+
26+
| Event Name | Description | Webhook Event |
27+
| ---------------------- | ------------------------------------------------ | ------------------------------ |
28+
| Granted ... [Currency] | Currency was added to the customer's balance | `VIRTUAL_CURRENCY_TRANSACTION` |
29+
| Spent ... [Currency] | Currency was removed from the customer's balance | `VIRTUAL_CURRENCY_TRANSACTION` |
30+
31+
### Event Details
32+
33+
When you click on a virtual currency event in the Customer History, you can view additional details including:
34+
35+
- The amount of currency granted or spent
36+
- The currency type and metadata
37+
- The product that triggered the transaction
38+
- The [source](/offerings/virtual-currency/events#source-values) of the transaction (`in_app_purchase`, `admin_api`)
39+
40+
## Webhook Events
41+
42+
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.
43+
44+
### When Events Are Sent
45+
46+
Virtual currency webhook events are triggered in the following scenarios:
47+
48+
- **In-app purchases**: When a customer purchases a product associated with virtual currency
49+
- **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
50+
- **Manual adjustments via dashboard**: When virtual currency is manually adjusted through the dashboard
51+
52+
### Event Structure
53+
54+
Virtual currency webhook events include standard webhook fields plus virtual currency-specific fields. Here's an example of a virtual currency transaction event:
55+
56+
import virtualCurrencyEvent from "@site/code_blocks/integrations/webhooks/sample-events_15.json?raw";
57+
58+
<RCCodeBlock
59+
tabs={[
60+
{
61+
type: "json",
62+
content: virtualCurrencyEvent,
63+
},
64+
]}
65+
/>
66+
67+
### Virtual Currency Specific Fields
68+
69+
| Field | Type | Description | Possible Values |
70+
| ------------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------- | ------------------------------ |
71+
| `adjustments` | Array | Array of virtual currency adjustments made in this transaction. Each adjustment contains the amount and currency details. | |
72+
| `adjustments[].amount` | Integer | The amount of virtual currency added (positive) or removed (negative) from the customer's balance. | |
73+
| `adjustments[].currency` | Object | Details about the virtual currency involved in the transaction. | |
74+
| `adjustments[].currency.code` | String | The unique identifier for the virtual currency. | |
75+
| `adjustments[].currency.name` | String | The display name of the virtual currency. | |
76+
| `adjustments[].currency.description` | String | The description of the virtual currency. | |
77+
| `product_display_name` | String | The display name of the product that triggered the virtual currency transaction. | |
78+
| `purchase_environment` | String | The environment where the product purchase was made. | `SANDBOX`, `PRODUCTION`. |
79+
| `source` | String | The source of the virtual currency transaction. | `in_app_purchase`, `admin_api` |
80+
| `virtual_currency_transaction_id` | String | Unique identifier for this virtual currency transaction. | |
81+
82+
### Source Values
83+
84+
The `source` field indicates what triggered the virtual currency balance adjustment:
85+
86+
- `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
87+
- `admin_api`: Currency was manually adjusted through the dashboard
88+
89+
### Multiple Currency Adjustments
90+
91+
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.
92+
93+
Example of a multi-currency transaction:
94+
95+
```json
96+
{
97+
"adjustments": [
98+
{
99+
"amount": 1000,
100+
"currency": {
101+
"code": "GLD",
102+
"name": "Gold",
103+
"description": "Premium currency"
104+
}
105+
},
106+
{
107+
"amount": 50,
108+
"currency": {
109+
"code": "SLV",
110+
"name": "Silver",
111+
"description": "Standard currency"
112+
}
113+
}
114+
]
115+
}
116+
```
117+
118+
## Best Practices
119+
120+
### Monitoring
121+
122+
- **Balance Reconciliation**: Use webhook events to reconcile virtual currency balances with your internal systems
123+
- **Fraud Detection**: Monitor for unusual patterns in virtual currency transactions
124+
- **Customer Support**: Use timeline events to help customers understand their transaction history
125+
126+
## Next Steps
127+
128+
- [Webhook Event Types and Fields](/integrations/webhooks/event-types-and-fields#virtual-currency-transaction-fields)
129+
- [Customer History](/dashboard-and-metrics/customer-history)
130+
- [Virtual Currency Subscriptions](/offerings/virtual-currency/subscriptions)
131+
- [Virtual Currency Refunds](/offerings/virtual-currency/refunds)

‎sidebars.ts

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -321,7 +321,11 @@ const offeringsCategory = Category({
321321
label: "Virtual Currency",
322322
slug: "offerings/virtual-currency",
323323
itemsPathPrefix: "offerings/virtual-currency/",
324-
items: [Page({ slug: "subscriptions" }), Page({ slug: "refunds" })],
324+
items: [
325+
Page({ slug: "subscriptions" }),
326+
Page({ slug: "refunds" }),
327+
Page({ slug: "events" }),
328+
],
325329
}),
326330
Page({ slug: "offerings/troubleshooting" }),
327331
],

‎static/docs_images/virtual-currency/vc-customer-history-timeline.png

229 KB
Loading

0 commit comments

Comments
 (0)