Event type: Monetization
Monetization events are related to user actions in relation to offers. This includes events when the user do their initial purchase as well as when the subscription is renewed, renewal fails, removed etc.
The available events are:
- Purchased
- Subscription Renewed
- Subscription Renewal Failed
- Subscription Upgraded
- Subscription Canceled
- Subscription Undo Canceled
- Subscription Removed
Purchased
Trigger:
When a user goes through the purchase flow and successfully purchases something, it triggers an event with type monetization.purchased. The event is triggered whether the user starts a subscription or rents a movie, and whether the user starts a trial, uses a promotion for 100% or actually pays. The payment object identifies the payment: payment.reference is always included, and payment.gateway and payment.gatewayReference are included when the payment went through a payment gateway.
Type:
monetization.purchased
Payload
{
"type": "monetization.purchased",
"timestamp": "2024-04-15T12:48:16.557Z",
"data": {
"userId": "XXXXXXXXXXXXXXXXXXXXXXXXXUSR",
"offerId": "XXXXXXXXXXXXXXXXXXXXXXXXXOFR",
"promoCode": "BOYSSXQWH",
"price": {
"currency": "USD",
"netPriceCents": 657,
"grossPriceCents": 900
},
"trialDurationSeconds": 259200,
"payment": {
"reference": "XXXXXXXXXXXXXXXXXXXXXXXXXPTI",
"gateway": "adyen",
"gatewayReference": "XXXXXXXXXXXXXXXX"
}
}
}Subscription Renewed
Trigger:
An event of type monetization.subscription.renewed is triggered when a subscription is renewed. This happens both when a user goes from a free trial to an active subscription, and when the subscription is renewed according to its periodicity (monthly or yearly). A renewed event is triggered whether the user has a 100% discount or money is withdrawn from the user's payment method. price shows what was charged for the renewal: a renewal at 100% discount has netPriceCents 0, with grossPriceCents at the offer's full price. promoCode is included when the renewal was made with a promo code.
Type:
monetization.subscription.renewed
Payload
Full-price renewal:
{
"type": "monetization.subscription.renewed",
"timestamp": "2024-04-17T05:39:51.616Z",
"data": {
"userId": "XXXXXXXXXXXXXXXXXXXXXXXXXUSR",
"offerId": "XXXXXXXXXXXXXXXXXXXXXXXXXOFR",
"price": {
"currency": "EUR",
"netPriceCents": 999,
"grossPriceCents": 999
},
"payment": {
"reference": "XXXXXXXXXXXXXXXXXXXXXXXXXPTI",
"gateway": "adyen",
"gatewayReference": "XXXXXXXXXXXXXXXX"
}
}
}Renewal at 100% discount with a promo code. No payment gateway is involved, so payment has only reference:
{
"type": "monetization.subscription.renewed",
"timestamp": "2024-04-17T05:39:51.616Z",
"data": {
"userId": "XXXXXXXXXXXXXXXXXXXXXXXXXUSR",
"offerId": "XXXXXXXXXXXXXXXXXXXXXXXXXOFR",
"promoCode": "BOYSSXQWH",
"price": {
"currency": "EUR",
"netPriceCents": 0,
"grossPriceCents": 999
},
"payment": {
"reference": "XXXXXXXXXXXXXXXXXXXXXXXXXPTI"
}
}
}Subscription Renewal Failed
Trigger:
Sometimes a renewal fails for a user, which triggers an event of type monetization.subscription.renewal_failed. This happens when money can't be withdrawn from the user's account. Depending on the retry strategy, this event may be triggered multiple times, a certain number of days apart, before the user's subscription is downgraded. payment.gateway and payment.gatewayReference are only included if the payment reached the payment gateway. A renewal that fails before that, for example without a valid payment method, has only payment.reference.
Type:
monetization.subscription.renewal_failed
Payload
Refused by Adyen:
{
"type": "monetization.subscription.renewal_failed",
"timestamp": "2024-04-17T05:39:51.616Z",
"data": {
"userId": "XXXXXXXXXXXXXXXXXXXXXXXXXUSR",
"offerId": "XXXXXXXXXXXXXXXXXXXXXXXXXOFR",
"attempt": 1,
"payment": {
"reference": "XXXXXXXXXXXXXXXXXXXXXXXXXPTI",
"gateway": "adyen",
"gatewayReference": "XXXXXXXXXXXXXXXX"
}
}
}Failed before reaching the gateway, e.g. no valid payment method:
{
"type": "monetization.subscription.renewal_failed",
"timestamp": "2024-04-17T05:39:51.616Z",
"data": {
"userId": "XXXXXXXXXXXXXXXXXXXXXXXXXUSR",
"offerId": "XXXXXXXXXXXXXXXXXXXXXXXXXOFR",
"attempt": 2,
"payment": {
"reference": "XXXXXXXXXXXXXXXXXXXXXXXXXPTI"
}
}
}Subscription Upgraded
Trigger:
A user can upgrade their subscription to a more expensive Offer, e.g. from a Monthly to a Yearly subscription, or from Basic to Premium. When this happens, an event of type monetization.subscription.upgraded is triggered. price.netPriceCents is the amount charged for the upgrade, after a credit for the unused part of the original Offer, and price.grossPriceCents is the price of the new Offer. A monetization.subscription.removed event with reason SubscriptionUpgrade is also sent for the original Offer. The two events can arrive in either order.
Type:
monetization.subscription.upgraded
Payload
{
"type": "monetization.subscription.upgraded",
"timestamp": "2024-04-15T12:49:18.314Z",
"data": {
"originalOfferId": "XXXXXXXXXXXXXXXXXXXXXXXXXOFR",
"userId": "XXXXXXXXXXXXXXXXXXXXXXXXXUSR",
"offerId": "YYYYYYYYYYYYYYYYYYYYYYYYYOFR",
"price": {
"currency": "EUR",
"netPriceCents": 6300,
"grossPriceCents": 6999
},
"payment": {
"reference": "XXXXXXXXXXXXXXXXXXXXXXXXXPTI",
"gateway": "adyen",
"gatewayReference": "XXXXXXXXXXXXXXXX"
}
}
}Subscription Canceled
Trigger:
If a user decides to cancel their subscription, an event of type monetization.subscription.canceled will be triggered. This events only signal that the subscription have canceled the subscription but they will keep Entitlement to the Offer until the billing period ends.
Type:
monetization.subscription.canceled
Payload
{
"type": "monetization.subscription.canceled",
"timestamp": "2024-04-15T12:52:44.511872093Z",
"data": {
"userId": "XXXXXXXXXXXXXXXXXXXXXXXXXUSR",
"offerId": "YYYYYYYYYYYYYYYYYYYYYYYYYOFR"
}
}Subscription Undo Canceled
Trigger:
If a user undo the cancelation of their subscription, it means that the billing and renewal process will continue as it was before the cancelation. When the user undo the cancelation, it will trigger an event of type monetization.subscription.undo_canceled.
Type:
monetization.subscription.undo_canceled
Payload
{
"type": "monetization.subscription.undo_canceled",
"timestamp": "2024-04-18T08:12:58.063460256Z",
"data": {
"userId": "XXXXXXXXXXXXXXXXXXXXXXXXXUSR",
"offerId": "YYYYYYYYYYYYYYYYYYYYYYYYYOFR"
}
}Subscription Removed
Trigger:
When a subscription is removed from a user and they loose the Entitlement to that Offer, an event of type monetization.subscription.removed is triggered. There's different underlying reasons for why a subscription is removed. The property reason in the payload will indicate which reason triggered that specific event.
Available reasons for subscription removed:
- SoftCancel - When a user have canceled their subscription and the subscription is removed when the billing period ends.
- DunningDowngrade - When all renewal attempts fails for a user and the subscription is downgraded.
- SubscriptionUpgrade - When a subscription is upgraded, a
removedevent is triggered with the offer ID of the Offer that the user upgraded from. Amonetization.subscription.upgradedevent is sent for the new Offer, and the two events can arrive in either order. - HardCancel - When a subscription is removed before the billing period ends. Can be done through the Magine Pro Console.
Type:
monetization.subscription.removed
Payload
{
"type": "monetization.subscription.removed",
"timestamp": "2024-04-15T12:49:20.019457004Z",
"data": {
"userId": "XXXXXXXXXXXXXXXXXXXXXXXXXUSR",
"offerId": "XXXXXXXXXXXXXXXXXXXXXXXXXOFR",
"reason": "SubscriptionUpgrade"
}
}Parameters
In the various events, the included parameters inside the data object will vary between the different events and what was actually added or changed in the user object. These are the parameters that can be included:
| Field | Type | Description |
|---|---|---|
| userId | string | ID of the user. |
| offerId | string | ID of the offer. |
| promoCode | string | Promo code used in the purchase or renewal. Included in purchased and subscription.renewed when a promo code was used. |
| price | object | Object that will contain all properties related to the price and what the user have paid. |
| price.currency | string | Currency of the offer. |
| price.netPriceCents | integer | Net price in the sub-currency of the offer. E.g. If the net price is 3.99 EUR, then netPriceCents would be 399. |
| price.grossPriceCents | integer | Price of the offer before any discounts have been applied. Gross price is also in the sub-currency. |
| trialDurationSeconds | integer | The length in seconds of the free trial the user will have. Only included in the purchased event. |
| attempt | integer | Indicates which attempt in the retry strategy that triggered this event i.e. first, second etc. Only included for subscription.renewal_failed. |
| originalOfferId | string | In the subscription.upgraded event the property originalOfferId is included. This is the offer that the user had before they did the upgrade of their subscription. |
| reason | string | The underlying reason of why a subscription have been removed from a user. Only included in the subscription.removed event. |
| payment | object | The payment behind the event. In purchased, renewed, upgraded and renewal_failed. |
| payment.reference | string | Our ID for the payment, ending in PTI. Always included. We also send it to the payment gateway: in Adyen, it's the payment's Merchant Reference. In Stripe, it's the payment's transaction_id metadata. |
| payment.gateway | string | The payment gateway, e.g. adyen or stripe. Left out when the payment didn't go through a gateway, e.g. a €0 renewal or a 100% promotion. |
| payment.gatewayReference | string | The gateway's own ID for the payment. For Adyen, the pspReference. Left out when not available, e.g. for Stripe. |
Fields without a value are left out of the payload. New fields may be added to events over time, so make sure your integration ignores fields it doesn't recognize.
Updated 6 days ago