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

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 removed event is triggered with the offer ID of the Offer that the user upgraded from. A monetization.subscription.upgraded event 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:

FieldTypeDescription
userIdstringID of the user.
offerIdstringID of the offer.
promoCodestringPromo code used in the purchase or renewal. Included in purchased and subscription.renewed when a promo code was used.
priceobjectObject that will contain
all properties related to
the price and what the user
have paid.
price.currencystringCurrency of the offer.
price.netPriceCentsintegerNet price in the sub-currency
of the offer. E.g. If the net price is
3.99 EUR, then netPriceCents
would be 399.
price.grossPriceCentsintegerPrice of the offer before any discounts
have been applied. Gross price is also
in the sub-currency.
trialDurationSecondsintegerThe length in seconds of the free trial
the user will have. Only included in the
purchased event.
attemptintegerIndicates which attempt in the retry strategy
that triggered this event i.e. first, second etc.
Only included for subscription.renewal_failed.
originalOfferIdstringIn 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.
reasonstringThe underlying reason of why a subscription
have been removed from a user. Only included
in the subscription.removed event.
paymentobjectThe payment behind the event. In purchased, renewed, upgraded and renewal_failed.
payment.referencestringOur 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.gatewaystringThe 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.gatewayReferencestringThe 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.