Skip to main content
Start selling

Retrieve an event

GET 
https://api.freemius.com/v1/products/{product_id}/events/{event_id}.json

Auth:Bearer TokenSCOPE: PRODUCT

Product-scoped API tokens allow you to operate on the product itself. This token usually allows read-only access to the product configuration and write access to several operations on subscriptions, customers, payments, and more. For most SaaS or app integrations, this is the token you will need.

  1. Go to the Freemius Developer Dashboard.
  2. Open the Settings page of the relevant product.
  3. Click the API & Keys tab.
  4. Copy the API Bearer Authorization Token from the UI.

Retrieve a specific event by its ID. For instructions on creating webhook listeners, see the documentation.

Request​

Path Parameters

    product_id integer<int64>required

    The ID of the product.

    Possible values: >= 1

    Example: 1234
    event_id integer<int64>required

    The ID of the event.

    Possible values: >= 1

    Example: 1234

Query Parameters

    fields string

    Comma separated list of fields to return in the response. If not specified, all fields are returned.

    Example: id,name,slug

Responses​

The retrieved event.

Schema
statestring

State of the event log. It essentially says whether the event was processed through the webhook or not.

Possible values: [processed, pending, canceled, error]

idstring<int64>

The unique identifier of the entity.

Possible values: >= 1

Example: 123456
createdstring<date-time>

The date and time the entity was created, under UTC timezone.

Example: 2025-01-01 00:00:00
updatedstring<date-time>nullable

The date and time the entity was updated, under UTC timezone. If null then the entity was never updated since its creation.

Example: 2025-01-01 00:00:00
typestring

The type of event. See our documented list of the available event types.

Example: license.activated
developer_idstring<int64>

The ID of the developer.

Possible values: >= 1

Example: 1234
plugin_idstring<int64>nullable

The ID of the product the entity belongs to. Null means it has not been associated with a product yet.

Possible values: >= 1

Example: 123456
user_idstring<int64>nullable

The ID of the user the entity belongs to. If NULL then still not associated to any user.

Possible values: >= 1

Example: 123456
install_idstring<int64>nullable

The ID of the installation or site the entity is associated with, a null value means it has not been associated with an installation yet.

Possible values: >= 1

Example: 123456
datanullable

The details of the triggered event. This can be a string showing ID of the associated entity, an object with additional information of the event, or array of objects.

event_triggerstring

The type of trigger for the event.

Possible values: [system, developer, plugin, user, install]

Example: system
process_timestring<date-time>nullable

The time the event was processed. If it is null, the event is pending.

Example: 2025-01-01 12:00:00
objects object

A map of related objects keyed by their type or ID, such as Payment, User, Install, or License.

user objectnullable
oneOf
notestring

A note about the user. Only visible to the developer.

is_marketing_allowedbooleannullable

Whether the user has consented for marketing notifications.

is_betaboolean

Whether or not the user has opted-in to beta versions. We do not recommend using this option anymore since it will opt-in the user to all sites/activations. Currently, sites or activations can be managed individually.

emailstring

Email address of the person.

Example: [email protected]
firststring

First name of the person.

Example: Jane
laststring

Last name of the person.

Example: Doe
picturestring

Profile picture URL.

Example: https://example.com/profile-pic.jpg
ipstring<ipv4|ipv6>nullable

The IP address (v4 or v6).

Example: 127.0.0.1
is_verifiedboolean

Whether the person is trusted or not.

Example: true
authstring

The type of authentication. If app2fa is set, the person has signed for 2FA authentication.

Possible values: [app2fa, password]

secret_keystring

The secret key associated with the entity for authorization.

Example: sk_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
public_keystring

The public key associated with the entity for authorization.

Example: pk_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
idstring<int64>

The unique identifier of the entity.

Possible values: >= 1

Example: 123456
createdstring<date-time>

The date and time the entity was created, under UTC timezone.

Example: 2025-01-01 00:00:00
updatedstring<date-time>nullable

The date and time the entity was updated, under UTC timezone. If null then the entity was never updated since its creation.

Example: 2025-01-01 00:00:00
grossnumber<float>

Gross payments made by the user for the product

Example: 999
last_login_atstring<date-time>nullable

Date and time of the last login.

Example: 2025-07-30 05:56:29
email_statusstring

The status of the last email sent to the user.

Possible values: [delivered, bounce, dropped]

plugin_idstring<int64>

The ID of the product the entity belongs to.

Possible values: >= 1

Example: 123456
user_idstring<int64>

The ID of the user the entity belongs to.

Possible values: >= 1

Example: 123456
install objectnullable
oneOf
secret_keystring

The secret key associated with the entity for authorization.

Example: sk_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
public_keystring

The public key associated with the entity for authorization.

Example: pk_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
idstring<int64>

The unique identifier of the entity.

Possible values: >= 1

Example: 123456
createdstring<date-time>

The date and time the entity was created, under UTC timezone.

Example: 2025-01-01 00:00:00
updatedstring<date-time>nullable

The date and time the entity was updated, under UTC timezone. If null then the entity was never updated since its creation.

Example: 2025-01-01 00:00:00
site_idstring<int64>

The ID of the site.

Example: 1234
plugin_idstring<int64>

The ID of the product the entity belongs to.

Possible values: >= 1

Example: 123456
user_idstring<int64>

The ID of the user the entity belongs to.

Possible values: >= 1

Example: 123456
urlstringnullable

The site URL.

Example: https://example.com
titlestringnullable

The site title.

Example: Catwalk Designs
versionstring

The Product version.

Example: 1.0.0
plan_idstring<int64>

The ID of the plan associated with the product that the install has a license activation. If null it means the install is using the free plan.

Possible values: >= 1

Example: 1234
license_idstring<int64>nullable

The ID of the license associated with the entity.

Possible values: >= 1

Example: 123456
trial_plan_idstring<int64>

The ID of the trial license associated to the product. If this is not a trial, this will be null.

Possible values: >= 1

Example: 1234
trial_endsstring<date-time>nullable

The product trial license expiry date. If this is not a trial, this will be null.

Example: 2025-01-01 00:00:00
subscription_idstring<int64>nullable

The ID of the subscription associated with the entity.

Possible values: >= 1

Example: 123456
grossnumber<float>

The gross amount the install has spent on the product. This includes one time purchase, or subscriptions and renewals.

Example: 100
country_codestringnullable

The ISO 3166-1 alpha 2 two-letter country code associated with the entity.

Example: us
languagestringnullable

The language specified for the product install.

Example: en-GB
platform_versionstringnullable

The platform version (e.g WordPress version).

Example: 1.0.0
sdk_versionstringnullable

The Freemius SDK version. Only relevant for WordPress products using the Freemius WP SDK.

Example: 1.2.2
programming_language_versionstringnullable

The programming language version (e.g PHP version).

Example: 5.6
is_activeboolean

If the product is actively installed on the site.

is_disconnectedboolean

If the product is disconnected on the site.

is_premiumboolean

If the install using the premium code. Relevant only for WP Products.

is_uninstalledboolean

If the product is uninstalled on the site.

is_lockedboolean

If the product is locked on the site.

sourcenumber

The source of the migration data. To get support migrating from other platform please see our documentation.

  • 0 - Freemius
  • 1 - Other
  • 2 - Easy Digital Downloads (EDD)
  • 3 - WooCommerce (WC)
  • 4 - Rating Widget
  • 5 - Gumroad
  • 6 - CodeCanyon
  • 7 - ThemeForest
  • 8 - AppSumo
  • 9 - SendOwl
  • 10 - WHMCS
  • 11 - Lemon Squeezy

Possible values: [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11]

upgradedstring<date-time>nullable

Time when the product was upgraded to the current version. If never upgraded since the initial installation, this will be null.

Example: 2025-01-01 00:00:00
last_seen_atstring<date-time>nullable

The last time the product was used on the site.

Example: 2025-01-01 00:00:00
last_served_update_versionstringnullable

The last product version update used on the site. If not updated, this will be null.

Example: 1.2.2
payment objectnullable
oneOf
user_idstring<int64>

The ID of the user the entity belongs to.

Possible values: >= 1

Example: 123456
install_idstring<int64>nullable

The ID of the installation or site the entity is associated with, a null value means it has not been associated with an installation yet.

Possible values: >= 1

Example: 123456
plan_idstring<int64>

The ID of the plan associated with the entity.

Possible values: >= 1

Example: 123456
pricing_idstring<int64>

The ID of the pricing associated with the entity.

Possible values: >= 1

Example: 123456
license_idstring<int64>

The ID of the license associated with the entity.

Possible values: >= 1

Example: 123456
ipstring<ipv4|ipv6>nullable

The IP address associated with the entity.

Example: 0.0.0.0
country_codestring

The ISO 3166-1 alpha 2 two-letter country code associated with the entity.

Example: us
zip_postal_codestringnullable

The postal/zip code of the location.

Example: 92710
vat_idstringnullable

The business VAT number (EU or UK territories) or other tax ID (for example Sales Tax ID for the US).

Example: GB12345678
coupon_idstring<int64>nullable

The ID of the coupon associated with the entity.

Possible values: >= 1

Example: 123456
user_card_idstring<int64>

The ID of the user card that was used for this payment.

Example: 12345
sourcenumber

The source of the migration data. To get support migrating from other platform please see our documentation.

  • 0 - Freemius
  • 1 - Other
  • 2 - Easy Digital Downloads (EDD)
  • 3 - WooCommerce (WC)
  • 4 - Rating Widget
  • 5 - Gumroad
  • 6 - CodeCanyon
  • 7 - ThemeForest
  • 8 - AppSumo
  • 9 - SendOwl
  • 10 - WHMCS
  • 11 - Lemon Squeezy

Possible values: [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11]

plugin_idstring<int64>

The ID of the product the entity belongs to.

Possible values: >= 1

Example: 123456
external_idstring

The external ID of the gateway entity.

Example: abcde12345
gatewaystringnullable

The gateway used for the purchase. The gateway will be set to null when purchasing a product with a 100% discount.

environmentnumber

The environment the entity belongs to. 0 means it belongs to the production environment, 1 means it belongs to the sandbox environment.

Possible values: [1, 0]

Example: 0
idstring<int64>

The unique identifier of the entity.

Possible values: >= 1

Example: 123456
createdstring<date-time>

The date and time the entity was created, under UTC timezone.

Example: 2025-01-01 00:00:00
updatedstring<date-time>nullable

The date and time the entity was updated, under UTC timezone. If null then the entity was never updated since its creation.

Example: 2025-01-01 00:00:00
currencystring

3-char currency code.

Possible values: >= 3 characters and <= 3 characters, [usd, eur, gbp]

refund_reasonstringnullable
Example: Refunded due to a bug in the plugin.
subscription_idstring<int64>nullable

The ID of the subscription associated with the entity.

Possible values: >= 1

Example: 123456
payment_presentment_idstring<int64>

The ID of the presentment payment.

Possible values: >= 1

Example: 123456
grossnumber<float>

The payment amount (not including taxes).

Example: 2075.45
bound_payment_idstring<int64>

The ID of the payment that this payment is bound to, in case of a refund or chargeback/dispute.

Possible values: >= 1

Example: 123456
gateway_feenumber<float>
Default value: 0

The fee that the gateway took for processing this payment.

Example: 2.99
vatnumber
Default value: 0

The actual tax amount. It could be any kind of tax, not necessarily VAT. For example we support US Sales Tax.

Example: 1.24
is_renewalboolean
Default value: false

If the payment is a renewal.

typestring
Default value: payment

The type of the payment.

Possible values: [payment, refund, disputed, won_dispute, lost_dispute, chargeback]

subscription objectnullable
oneOf
user_idstring<int64>

The ID of the user the entity belongs to.

Possible values: >= 1

Example: 123456
install_idstring<int64>nullable

The ID of the installation or site the entity is associated with, a null value means it has not been associated with an installation yet.

Possible values: >= 1

Example: 123456
plan_idstring<int64>

The ID of the plan associated with the entity.

Possible values: >= 1

Example: 123456
pricing_idstring<int64>

The ID of the pricing associated with the entity.

Possible values: >= 1

Example: 123456
license_idstring<int64>

The ID of the license associated with the entity.

Possible values: >= 1

Example: 123456
ipstring<ipv4|ipv6>nullable

The IP address associated with the entity.

Example: 0.0.0.0
country_codestring

The ISO 3166-1 alpha 2 two-letter country code associated with the entity.

Example: us
zip_postal_codestringnullable

The postal/zip code of the location.

Example: 92710
vat_idstringnullable

The business VAT number (EU or UK territories) or other tax ID (for example Sales Tax ID for the US).

Example: GB12345678
coupon_idstring<int64>nullable

The ID of the coupon associated with the entity.

Possible values: >= 1

Example: 123456
user_card_idstring<int64>

The ID of the user card that was used for this payment.

Example: 12345
sourcenumber

The source of the migration data. To get support migrating from other platform please see our documentation.

  • 0 - Freemius
  • 1 - Other
  • 2 - Easy Digital Downloads (EDD)
  • 3 - WooCommerce (WC)
  • 4 - Rating Widget
  • 5 - Gumroad
  • 6 - CodeCanyon
  • 7 - ThemeForest
  • 8 - AppSumo
  • 9 - SendOwl
  • 10 - WHMCS
  • 11 - Lemon Squeezy

Possible values: [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11]

plugin_idstring<int64>

The ID of the product the entity belongs to.

Possible values: >= 1

Example: 123456
external_idstring

The external ID of the gateway entity.

Example: abcde12345
gatewaystringnullable

The gateway used for the purchase. The gateway will be set to null when purchasing a product with a 100% discount.

environmentnumber

The environment the entity belongs to. 0 means it belongs to the production environment, 1 means it belongs to the sandbox environment.

Possible values: [1, 0]

Example: 0
idstring<int64>

The unique identifier of the entity.

Possible values: >= 1

Example: 123456
createdstring<date-time>

The date and time the entity was created, under UTC timezone.

Example: 2025-01-01 00:00:00
updatedstring<date-time>nullable

The date and time the entity was updated, under UTC timezone. If null then the entity was never updated since its creation.

Example: 2025-01-01 00:00:00
currencystring

3-char currency code.

Possible values: >= 3 characters and <= 3 characters, [usd, eur, gbp]

tax_ratenumber<float>

The tax rate as a fraction. It will either be US sales tax or VAT.

Possible values: >= 0

Example: 1.00
total_grossnumber<float>

The total gross amount of the subscription, including taxes.

Possible values: >= 0

Example: 1.21
amount_per_cyclenumber<float>

The plan's original amount per cycle (not including taxes).

Possible values: >= 0

Example: 1.00
initial_amountnumber<float>

The initial payment amount (not including taxes).

Possible values: >= 0

Example: 1.00
renewal_amountnumber<float>

The renewals amount (not including taxes).

Possible values: >= 0

Example: 1.00
renewals_discountinteger

The renewals discount that will be applied to the chosen plan.

Possible values: >= 0

Example: 1
renewals_discount_typestring

The type of renewals discount, percentage or dollar.

Possible values: [percentage, dollar]

billing_cyclenumber

The billing cycle of the subscription in number of months. 1 means monthly, 12 means annually, 0 means lifetime usually when subscriptions are created for lifetime trials.

Possible values: [1, 12, 0]

outstanding_balancenumber<float>

Any outstanding balance that the user has for this subscription.

Possible values: >= 0

Example: 1.00
failed_paymentsinteger

Number of failed payments associated with the subscription.

Possible values: >= 0

Example: 1
trial_endsstring<date-time>nullable

The date time when the trial period ends. If null the subscription is not associated with a trial.

Example: 2025-01-01 00:00:00
next_paymentstring<date-time>nullable

Datetime of the next payment, or null if cancelled.

Example: 2025-01-01 00:00:00
canceled_atstring<date-time>nullable

Datetime of the cancellation.

Example: 2025-01-01 00:00:00
license objectnullable
oneOf
idstring<int64>

The unique identifier of the entity.

Possible values: >= 1

Example: 123456
createdstring<date-time>

The date and time the entity was created, under UTC timezone.

Example: 2025-01-01 00:00:00
updatedstring<date-time>nullable

The date and time the entity was updated, under UTC timezone. If null then the entity was never updated since its creation.

Example: 2025-01-01 00:00:00
plugin_idstring<int64>

The ID of the product the entity belongs to.

Possible values: >= 1

Example: 123456
user_idstring<int64>nullable

The ID of the user the entity belongs to. If NULL then still not associated to any user.

Possible values: >= 1

Example: 123456
plan_idstring<int64>

The ID of the plan associated with the entity.

Possible values: >= 1

Example: 123456
pricing_idstring<int64>nullable

The ID of the pricing associated with the entity.

Possible values: >= 1

Example: 123456
quotaintegernullable

The maximum number of license activations. If null then the license will support unlimited activations.

Example: 10
activatedinteger

The total number of production activation the license has. This does not count local or staging environment activations.

Example: 1
activated_localintegernullable

The number of times the license is activated on local or staging environments.

Example: 1
expirationstring<date-time>nullable

The expiration date of the license. If null then it's a lifetime license.

Example: 2025-12-31 23:59:59
secret_keystring

The license key. This is used for activating the license on the user's site.

Example: sk_123FGqM456Pa786WtOp%^+67Y+;sXXz
is_free_localhostboolean
Default value: true

Whether the license offers unlimited local or staging environment activations.

is_block_featuresboolean
Default value: true

Whether to block features after expiration of the license. If set to false, this would not block features, would only block updates.

is_cancelledboolean

If the license is canceled from the Developer Dashboard.

is_whitelabeledboolean

Guide the Freemius WP SDK when the product should be running in a white-label mode.

environmentnumber

The environment the entity belongs to. 0 means it belongs to the production environment, 1 means it belongs to the sandbox environment.

Possible values: [1, 0]

Example: 0
sourcenumber

The source of the migration data. To get support migrating from other platform please see our documentation.

  • 0 - Freemius
  • 1 - Other
  • 2 - Easy Digital Downloads (EDD)
  • 3 - WooCommerce (WC)
  • 4 - Rating Widget
  • 5 - Gumroad
  • 6 - CodeCanyon
  • 7 - ThemeForest
  • 8 - AppSumo
  • 9 - SendOwl
  • 10 - WHMCS
  • 11 - Lemon Squeezy

Possible values: [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11]

property name*any

A map of related objects keyed by their type or ID, such as Payment, User, Install, or License.

We use essential cookies to enable our site to function. With your consent, we also use analytics and advertising cookies to understand how visitors interact with our site and to improve our services.
Learn More