Webhooks

Type

Event

Triggered By

Notes

subscription_created

new_purchase

User

Sent when end-user makes a purchase where a financial transaction took place. It will also fire when Print Subscription Confirmation (PSC) is redeemed. For free trials and free periods, the payment_verified event is sent instead.

subscription_created

payment_verified

User

Sent when a user signs up for a free trial or purchases a free dynamic term period.

subscription_created

term_applied_by_publisher

You

Sent when the end-user is subscribed to a term by the client representative and a financial transaction takes place.

subscription_created

payment_verified_by_publisher

You

Sent when end-user is subscribed to a term with a free trial or a free period.

subscription_created

term_change_finished

You, or User, or Piano

Sent when a subscription was successfully upgraded (specifically when a new subscription for this upgrade was created and payment was successful). Or when subscription entered the grace period upon upgrade had successfully exited the grace period.

subscription_created

term_change_grace_period_started

User or Piano

Sent when an upgrade was executed, but the newly created subscription for the new term entered a grace period because of the payment failure.

subscription_created

subscription_imported

Piano

Sent when a subscription was created by the import tool used by the Piano support team.

type

string

webhook type: subscription_created

version

string

2

typeTitle

string

webhook type title: Subscription created

event

string

event:

• new_purchase

• payment_verified

• term_applied_by_publisher

• payment_verified_by_publisher

• term_change_finished

• term_change_grace_period_started

• subscription_imported

eventTitle

string

event title:

• New purchase: for new_purchase event

• No payment purchase: for payment_verified event

• New purchase by publisher: for term_applied_by_publisher event

• No payment purchase by publisher: for payment_verified_by_publisher event

• Upgrade finished: for term_change_finished event

• Upgrade grace period started: for term_change_grace_period_started event

• Subscription imported: for subscription_imported event

aid

string

application id

uid

string

end-user id

user_email

string

end-user’s email address

term_id

string

term id

term_type

string

term type:

• DYNAMIC: for dynamic subscriptions

• PAYMENT: for recurring payment subscriptions;

rid

string

resource id

access_id

string

main access id, associated with subscription (access of subscription owner):

• <end-user’s access id>: for not shared subscription

• <PARENT end-user’s access id>: for shared subscription

subscription_id

string

subscription id

status

string

subscription status:

• ACTIVE

• COMPLETED

• PENDING

• NOT STARTED

create_date

long

subscription creation date

start_date

long

subscription start date (differs from subscription crate date for subscriptions purchased with the future start date and imported subscriptions)

next_bill_date

long

the value of the “next billing date” field of the subscription (not null):

billing_plan

string

billing plan of the last purchased period:

• <billing plan of the last purchased access period>: for dynamic subscription

• <full billing plan of the payment subscription>: for recurring payment subscription with or without trial; same value for the full life of the subscription

access_period_id

string

id of the access the last purchased access period:

• <access period id>: for dynamic subscription

• null: for payment subscription

active_billing_plan

string

billing plan of the active period:

• <billing plan of the active access period>: for dynamic subscription (active access period billing plan may be different from the last purchased access period billing plan in case of external manual renewal; for newly created subscription always the same value as in billing_plan parameter)

• <full billing plan of the payment subscription>: for recurring payment subscription with or without trial; same value for the full life of the subscription (always the same value as in billing_plan parameter for this type of subscription)

active_access_period_id

string

id of the access the active access period:

• <access period id>: for dynamic subscription (active access period may be different from the last purchased access period in case of external manual renewal; for newly created subscription always the same value as in access_period_id parameter)

• null: for payment subscription

upi_id

string

id of the renewal payment method associated with the subscription

auto_renew

boolean

the state of the auto-renew toggle associated with the subscription:

• true: auto-renewal enabled - for payment subscription; the only possible value for dynamic subscription

• false: auto-renewal disabled - for payment subscription; impossible value for dynamic subscription

is_in_grace

boolean

shows if the subscription is currently in grace period

grace_period_start_date

long

grace period start date

grace_period_length

int

grace period length in days

failure_counter

int

number of payment failures

passive_churn_logic_id

string

id of the churn prevention logic

decline_reason

string

decline reason for a payment attempt

payment_id

string

id of a payment associated with subscription creation

created_by

string

id of a user initiated the action that result in subscription creation

Type

Event

Triggered by

Notes

subscription_updated

subscription_activated

Piano

Sent when a subscription with a future start date is activated

subscription_updated

subscription_access_period_activated

Piano

Sent when dynamic subscription entered manually purchased next access period (via manual renew functionality)

subscription_updated

subscription_next_bill_date_updated

You

Sent when the subscription's next billing date is updated manually in UI or via API (not applicable for dynamic terms)

subscription_updated

subscription_payment_method_updated

You or User

Sent when payment method associated with a subscription is updated (changed)

subscription_updated

subscription_address_updated

You or User

Sent when the payment address associated with a subscription is updated (changed). Not when the address is edited

subscription_updated

subscription_shared_accounts_updated

You or User

Sent when the list of shared accounts of a subscription is updated: manually (via MA/PD/API) or automatically (when the shared subscription is purchased, imported, or upgraded).

subscription_updated

subscription_auto_renew_enabled

You or User

Sent when subscription's auto-renew status had been changed to enabled (only applicable for payment subscriptions)

subscription_updated

subscription_auto_renew_disabled

You or User

Sent when the subscription's auto-renew status had been changed to disabled (only applicable for payment subscriptions)

subscription_updated

subscription_dynamic_unlimited_period_converted

Piano

Sent when dynamic subscription unlimited period had been converted to a period of another type. Action initiated by You, but done asynchronously

subscription_updated

subscription_deferred_canceled

You or User

Sent when dynamic subscription had been canceled

subscription_updated

subscription_resumed

You or User

Sent when dynamic subscription had been resumed

subscription_updated

subscription_access_period_scheduled

You or Piano

Sent when a specific access period of dynamic subscription was selected for the next renewal

subscription_updated

subscription_access_period_unscheduled

You or Piano

Sent when specific access period of dynamic subscription was unselected for next renewal (renewal will occur according to currently up-to-date billing configuration)

subscription_updated

subscription_rescheduled

Piano

Sent when scheduled subscription is re-activated because there was a new period added to the schedule associated with the scheduled term

subscription_updated

subscription_grace_period_started

Piano

Sent when subscription entered grace period upon the automated renewal

subscription_updated

subscription_grace_period_ended

Piano

Sent when the subscription successfully exited the grace period upon the automated/manual renewal

subscription_updated

term_change_scheduled

You or User

Sent when a deferred upgrade was scheduled for a subscription

subscription_updated

term_change_canceled

You

Sent when a scheduled deferred upgrade was canceled by You

subscription_updated

term_change_suspended

User

Sent when a scheduled deferred upgrade was canceled by the end-user (this action also triggers a deferred subscription cancellation)

subscription_updated

term_change_resumed

User

Sent when subscription with the suspended deferred upgrade was resumed (this action also re-activates the subscription)

subscription_updated

term_change_grace_period_ended

Piano or User

Sent when a subscription that was in a grace period started upon the upgrade had successfully exited the grace period

type

string

webhook type: subscription_updated

version

string

2

typeTitle

string

webhook type title: Subscription updated

event

string

event:

• subscription_activated

• subscription_access_period_activated

• subscription_next_bill_date_updated

• subscription_payment_method_updated

• subscription_address_updated

• subscription_shared_accounts_updated

• subscription_auto_renew_enabled

• subscription_auto_renew_disabled

• subscription_dynamic_unlimited_period_converted

• subscription_deferred_canceled

• subscription_resumed

• subscription_access_period_scheduled

• subscription_access_period_unscheduled

• subscription_rescheduled

• subscription_grace_period_started

• subscription_grace_period_ended

• term_change_scheduled

• term_change_canceled

• term_change_suspended

• term_change_resumed

• term_change_grace_period_ended

eventTitle

string

event title:

• Subscription_activated: for subscription_activated event

• Subscription access period activated: for subscription_access_period_activated event

• Subscription next bill date updated: for subscription_next_bill_date_updated event

• Subscription payment method updated: for subscription_payment_method_updated event

• Subscription address updated: for subscription_address_updated event

• Subscription shared accounts updated: for subscription_shared_accounts_updated event

• Subscription auto-renew enabled: for subscription_auto_renew_enabled event

• Subscription auto-renew disabled: for subscription_auto_renew_disabled event

• Subscription unlimited period converted: for subscription_dynamic_unlimited_period_converted event

• Subscription canceled (deferred cancel): for subscription_deferred_canceled event

• Subscription resumed: for subscription_resumed event

• Subscription access period scheduled: for subscription_access_period_scheduled event

• Subscription access period unscheduled: for subscription_access_period_unscheduled event

• Scheduled subscription period activated: for subscription_rescheduled event

• Subscription renewal grace period started: for subscription_grace_period_started event

• Subscription renewal grace period ended: for subscription_grace_period_ended event

• Upgrade scheduled: for term_change_scheduled event

• Upgrade canceled: for term_change_canceled event

• Upgrade suspended: for term_change_suspended event

• Upgrade resumed: for term_change_resumed event

• Upgrade grace period ended: for term_change_grace_period_ended event

aid

string

application id

uid

string

end-user id

user_email

string

end-user’s email address

term_id

string

term id

term_type

string

term type:

• DYNAMIC: for dynamic subscriptions;

• PAYMENT: for recurring payment subscriptions;

rid

string

resource id

access_id

string

main access id, associated with subscription (access of subscription owner):

• <end-user’s access id>: for not shared subscription

• <PARENT end-user’s access id>: for shared subscription

subscription_id

string

subscription id

status

string

subscription status:

• ACTIVE

• FAIL_AND_RETRY

• COMPLETED

• PENDING

• NOT STARTED

create_date

long

subscription create date

start_date

long

subscription start date (differs from subscription crate date for subscriptions purchased with deferred start and imported subscriptions)

next_bill_date

long

the value of the “next billing date” field of the subscription (not null):

• <next auto-renewal of the subscription> (date in the future): for active subscription for which auto-renewal is expected

• <last auto-renewal/purchase date of the subscription> (date in the past): for inactive subscription or for an active subscription that normally should not have an auto-renewal date, because auto-renewal is not expected (subscription on unlimited period, subscription with disabled auto-renewal, subscription with scheduled upgrade etc.)

billing_plan

string

billing plan of the last purchased period:

• <billing plan of the last purchased access period>: for dynamic subscription

• <full billing plan of the payment subscription>: for recurring payment subscription with or without trial; same value for the full life of the subscription

access_period_id

string

id of the access the last purchased access period:

• <access period id>: for dynamic subscription

• null: for payment subscription

active_billing_plan

string

billing plan of the active period:

• <billing plan of the active access period>: for dynamic subscription (active access period billing plan may be different from the last purchased access period billing plan in case of external manual renewal)

• <full billing plan of the payment subscription>: for recurring payment subscription with or without trial; same value for the full life of the subscription (always the same value as in billing_plan parameter for this type of subscription)

active_access_period_id

string

id of the last access the active access period:

• <access period id>: for dynamic subscription (active access period may be different from the last purchased access period in case of external manual renewal)

• null: for payment subscription

upi_id

string

id of the renewal payment method associated with the subscription

auto_renew

boolean

the state of the auto-renew toggle associated with the subscription:

• true: auto-renewal enabled - for payment subscription; the only possible value for dynamic subscription

• false: auto-renewal disabled - for payment subscription; impossible value for dynamic subscription

shared_accounts

Array [UserSubscriptionAccount]

array of all shared accounts currently associated with the shared subscription (includes accounts with both redeemed and not redeemed accesses) - see the UserSubscriptionAccount model below

is_in_grace

boolean

shows if the subscription is currently in grace period

grace_period_start_date

long

grace period start date

grace_period_length

int

grace period length in days

failure_counter

int

number of payment failures

passive_churn_logic_id

string

id of the churn prevention logic

decline_reason

string

decline reason for a payment attempt

updated_by

string

id of a user initiated the action that resulted in subscription updating

Field

Type

Value

account_id

string

id of shared account (any item added to the list as a potential CHILD end-user, no matter if the access was redeemed or not, no matter if this shared account has an associated CHILD end-user or not)

user_id

string

id of CHILD end-user associated with shared account:

• <end-user’s id>: for accounts that have an associated CHILD end-user after access redemption

• null: for accounts that do not have an associated CHILD end-user yet (email is not registered in the application, access is not redeemed)

email

string

email of shared account:

• <shared account’s email>: for accounts that do not have an associated CHILD end-user yet

• <shared account’s email> = <end-user’s email>: for accounts that that have an associated CHILD end-user (user info must always be in sync with shared account info, after end-user appears)

• all other values are impossible for this webhook type

first_name

string

first name of shared account:

• <shared account’s first name>: for accounts that do not have an associated CHILD end-user yet

• <shared account’s first name> = <end-user’s first name>: for accounts that that have an associated CHILD end-user (user info must always be in sync with shared account info, after end-user appears)

• all other values are impossible for this webhook type

last_name

string

last name of shared account:

• <shared account’s last name>: for accounts that do not have an associated CHILD end-user yet

• <shared account’s last name> = <end-user’s last name>: for accounts that that have an associated CHILD end-user (user info must always be in sync with shared account info, after end-user appears)

• all other values are impossible for this webhook type

personal_name

string

personal name of shared account:

• <shared account’s first name> + <shared account’s last name>: for accounts that have both first and last name

• <shared account’s first name>, <shared account’s last name> or null: for accounts that do not have full info

• all other values are impossible for this webhook type

redeemed

long

CHILD access redemption date:

• <date-time of access manual/auto access redemption>: for accounts that have an associated CHILD end-user and redeemed access

• null: for accounts that do not have an associated CHILD end-user and redeemed access yet

• all other values are impossible for this webhook type

Type

Event

Triggered by

Notes

subscription_renewal

subscription_auto_renewed

Piano

Sent when Piano's system successfully auto-renews a user's subscription, including the successful completion of the grace period. If an auto-renewal fails, the subscription_auto_renewed_failure or subscription_auto_renewed_auth_failure event is sent instead.

subscription_renewal

subscription_manually_renewed

You or User

Sent when a user manually renews a subscription, or when you manually renew a user's subscription on the user's behalf.

subscription_renewal

subscription_auto_renewed_failure

Piano

Sent when Piano's system is unable to auto-renew a user's subscription due to any reason, but mostly because of the payment failure. This includes all cases of payment failure: immediate subscription expiration if there is no grace period, grace period starting after the first payment failure, all unsuccessful payment attempts in the grace period, and subscription expiration after the last payment attempt in the grace period. If an auto-renewal fails due to a 3DS authentication failure, the subscription_auto_renewed_auth_failure event is sent instead.

subscription_renewal

subscription_auto_renewed_auth_failure

Piano

Sent instead of the subscription_auto_renewed_failure event when an auto-renewal fails due to a 3DS authentication failure.

type

string

webhook type: subscription_renewal

version

string

2

typeTitle

string

webhook type title: Subscription renewal

event

string

event:

• subscription_auto_renewed

• subscription_manually_renewed

• subscription_auto_renewed_failure

• subscription_auto_renewed_auth_failure

eventTitle

string

event title:

• Subscription was automatically renewed: for subscription_auto_renewed event

• Subscription was manually renewed: for subscription_manually_renewed event

• Failure of automatic subscription renewal: for subscription_auto_renewed_failure event

• 3DS authentication payment error
during automatic subscription renewal: for subscription_auto_renewed_auth_failure event

aid

string

application id

uid

string

end-user id

user_email

string

end-user’s email address

term_id

string

term id

term_type

string

term type:

• DYNAMIC: for dynamic subscriptions;

• PAYMENT: for recurring payment subscriptions;

rid

string

resource id

access_id

string

main access id, associated with subscription (access of subscription owner):

• <end-user’s access id>: for not shared subscription

• <PARENT end-user’s access id>: for shared subscription

subscription_id

string

subscription id

status

string

subscription status:

• ACTIVE

• UPGRADED

create_date

long

subscription create date

start_date

long

subscription start date (differs from subscription crate date for subscriptions purchased with deferred start and imported subscriptions)

next_bill_date

long

the value of the “next billing date” field of the subscription (not null):

• <next auto-renewal of the subscription> (date in the future): for active subscription for which auto-renewal is expected

• <last auto-renewal/purchase date of the subscription> (date in the past): for inactive subscription or for active subscription that normally should not have auto-renewal date, because auto-renewal is not expected (subscription on unlimited period, subscription with disabled auto-renewal, subscription with scheduled upgrade etc.)

billing_plan

string

billing plan of the last purchased period:

• <billing plan of the last purchased access period>: for dynamic subscription

• <full billing plan of the payment subscription>: for recurring payment subscription with or without trial; same value for the full life of the subscription

access_period_id

string

id of the access the last purchased access period:

• <access period id>: for dynamic subscription

• null: for payment subscription

active_billing_plan

string

billing plan of the active period:

• <billing plan of the active access period>: for dynamic subscription (active access period billing plan may be different from the last purchased access period billing plan in case of external manual renewal)

• <full billing plan of the payment subscription>: for recurring payment subscription with or without trial; same value for the full life of the subscription (always the same value as in billing_plan parameter for this type of subscription)

active_access_period_id

string

id of the last access the active access period:

• <access period id>: for dynamic subscription (active access period may be different from the last purchased access period in case of external manual renewal)

• null: for payment subscription

upi_id

string

id of the renewal payment method associated with the subscription

auto_renew

boolean

the state of the auto-renew toggle associated with the subscription:

• true: auto-renewal enabled - for payment subscription; the only possible value for dynamic subscription

• false: auto-renewal disabled - for payment subscription; impossible value for dynamic subscription

shared_accounts

Array [UserSubscriptionAccount]

array of all shared accounts currently associated with the shared subscription (includes accounts with both redeemed and not redeemed accesses) - see the UserSubscriptionAccount model above

is_in_grace

boolean

shows if the subscription is currently in grace period

grace_period_start_date

long

grace period start date

grace_period_length

int

grace period length in days

failure_counter

int

number of payment failures

passive_churn_logic_id

string

id of the churn prevention logic

decline_reason

string

decline reason for a payment attempt

payment_id

string

id of a payment associated with subscription creation

renewal_type

string

renewal type:

• RENEWAL: for all renewals of recurring payment subscriptions, EVT subscriptions, linked subscriptions; for external renewal of dynamic subscription

• BILLING: for internal renewal of dynamic subscription

renewed_by

string

id of a user initiated the action that resulted in subscription updating

Type

Event

Triggered by

Notes

subscription_ended

subscription_canceled

You or User

Sent when a subscription is canceled using the immediate cancellation button

subscription_ended

subscription_expired

Piano

Sent when subscription renewal had failed and there is no grace period configured OR when subscription was canceled and not going to renew OR when there's no next access period configured in the term for this subscription

subscription_ended

term_change_aborted

Piano

Sent for subscription FROM when subscription with suspended upgrade reached renewal date and didn't upgrade

subscription_ended

term_change_finished

You, or User, or Piano

Sent for subscription FROM when subscription upgrade was successfully executed

subscription_ended

term_change_failure

Piano

Sent for the subscription FROM when a scheduled upgrade was not successful and there is no grace period configured in the term TO

subscription_ended

term_change_grace_period_started

Piano

Sent when an upgrade was executed, but the newly created subscription for the new term entered a grace period because of a payment failure.

type

string

webhook type: subscription_ended

version

string

2

typeTitle

string

webhook type title: Subscription ended

event

string

event:

• subscription_canceled

• subscription_expired

• term_change_aborted

• term_change_finished

• term_change_failure

• term_change_grace_period_started

eventTitle

string

event title:

• Subscription canceled (immediate cancel): for subscription_canceled event

• Subscritption expired: for subscription_expired event

• Upgrade aborted: for term_change_aborted event

• Upgrade finished: for term_change_finished event

• Upgrade failure: for term_change_failure event

• Upgrade grace period started: for term_change_grace_period_started event

aid

string

application id

uid

string

end-user id

user_email

string

end-user’s email address

term_id

string

term id

term_type

string

term type:

• DYNAMIC: for dynamic subscriptions;

• PAYMENT: for recurring payment subscriptions;

• all other values are impossible for this webhook type

rid

string

resource id

access_id

string

main access id, associated with subscription (access of subscription owner):

• <end-user’s access id>: for not shared subscription

• <PARENT end-user’s access id>: for shared subscription

subscription_id

string

subscription id

status

string

subscription status:

• CANCELLED

• EXPIRED_WITH_ERROR

• EXPIRED

• UPGRADED

create_date

long

subscription create date

start_date

long

subscription start date (differs from subscription crate date for subscriptions purchased with deferred start and imported subscriptions)

next_bill_date

long

the value of the “next billing date” field of the subscription (not null):

• <last auto-renewal/purchase date of the subscription> (date in the past): for inactive subscription or for an active subscription that normally should not have an auto-renewal date, because auto-renewal is not expected (subscription on unlimited period, subscription with disabled auto-renewal, subscription with scheduled upgrade etc.)

• all other values are impossible for this webhook type

billing_plan

string

billing plan of the last purchased period:

• <billing plan of the last purchased access period>: for dynamic subscription

• <full billing plan of the payment subscription>: for recurring payment subscription with or without trial; same value for the full life of the subscription

access_period_id

string

id of the access the last purchased access period:

• <access period id>: for dynamic subscription

• null: for payment subscription

active_billing_plan

string

billing plan of the last active period:

• <billing plan of the active access period>: for dynamic subscription (active access period billing plan may be different from the last purchased access period billing plan in case of external manual renewal)

• <full billing plan of the payment subscription>: for recurring payment subscription with or without trial; same value for the full life of the subscription (always the same value as in billing_plan parameter for this type of subscription)

active_access_period_id

string

id of the last access the active access period:

• <access period id>: for dynamic subscription (active access period may be different from the last purchased access period in case of external manual renewal)

• null: for payment subscription

upi_id

string

id of the renewal payment method associated with the subscription

auto_renew

boolean

the state of the auto-renew toggle associated with the subscription:

• true: auto-renewal enabled - for payment subscription; the only possible value for dynamic subscription

• false: auto-renewal disabled - for payment subscription; impossible value for dynamic subscription

shared_accounts

Array [UserSubscriptionAccount]

array of all shared accounts currently associated with the shared subscription (includes accounts with both redeemed and not redeemed accesses) - see the UserSubscriptionAccount model above

is_in_grace

boolean

shows if the subscription is currently in a grace period:

• false: subscription is not in the grace period of any type (ended subscription renewals are expected to be not in a grace period)

• all other values are impossible for this webhook type

grace_period_start_date

long

grace period start date:

• null: for subscription outside of a grace period (is_in_grace = false) (ended subscriptions renewal are expected to be not in a grace period)

• all other values are impossible for this webhook type

grace_period_length

int

grace period length in days:

• null: for subscription outside of a grace period (is_in_grace = false) (ended subscriptions renewal are expected to be not in a grace period)

• all other values are impossible for this webhook type

failure_counter

int

number of payment failures:

• <number of last failure> (1, 2, 3, 4… ): for subscriptions that become inactive after being in a grace period or after payment failure when the grace period could not start

• 0: for subscriptions that become inactive while having 0 as failure_counter value (outside of grace period but been in grace period at least once)

• null: for inactive subscriptions that have never been in a grace period

• all other values are impossible for this webhook type

passive_churn_logic_id

string

id of the churn prevention logic:

• <id>: for subscriptions that become inactive while being in a grace period (is_in_grace = true) when the passive churn prevention feature is enabled

• null: for inactive subscription when the passive churn prevention feature is disabled

• all other values are impossible for this webhook type

decline_reason

string

decline reason for a payment attempt:

• <reason>: for all cases when passive_churn_logic_id has a value

• null: for all cases when passive_churn_logic_id doesn’t have a value

ended_by

string

id of a user initiated the action that resulted in the subscription ending:

• <end-user’s id>: subscription cancellation (immediate cancel) via MA

• <client user’s id>: subscription cancellation (immediate cancel) via PD/API

• <admin user’s id>: subscription cancellation (immediate cancel) via AD

• null: expiration of a payment subscription with disabled auto-renewal; expiration of a canceled subscription (deferred cancel); expiration of a subscription with suspended pending upgrade; pending individual upgrade scheduled via MA/PD/onsite/API successful/unsuccessful execution; pending upgrade scheduled in bulk successful/unsuccessful execution; renewal failure with no grace period; payment failure on the last additional attempt in grace period after failure on upgrade or renewal

Type

Event

Triggered by

Notes

term_change

term_change_scheduled

You or User

Sent when a user initiates a pending upgrade of their subscription, or when you initiate a pending upgrade of a user's subscription (including bulk upgrades).

term_change

term_change_finished

You, or User, or Piano

Sent when a user immediately upgrades their subscription, or when you immediately upgrade a user's subscription on the user's behalf. Also sent when Piano's system successfully completes a previously scheduled pending upgrade of a user's subscription, including the successful completion of the grace period. If an upgrade fails, the term_change_failure event is sent instead.

 term_change

 term_change_canceled

You

Sent when you cancel a previously scheduled pending upgrade of a user's subscription on the user's behalf.

 term_change

 term_change_suspended

 User

Sent when a user suspends a previously scheduled pending upgrade of their subscription.

 term_change

 term_change_resumed

User

Sent when a user resumed a previously suspended pending upgrade of their subscription.

term_change

 term_change_aborted

Piano

Sent when subscription with suspended upgrade reached renewal date and didn't upgrade

 term_change

 term_change_failure

Piano

Sent when Piano's system is unable to complete a previously scheduled pending upgrade of a user's subscription due to any reason, but mostly because of the payment failure. This includes all cases of payment failure: immediate old subscription expiration without creating a new one if there is no grace period, grace period start for a new subscription after first payment failure, all unsuccessful payment attempts in the grace period, new subscription expiration after last payment attempt in the grace period.

 term_change

term_change_grace_period_started

Piano

Sent when an upgrade was executed, but the newly created subscription for the new term entered a grace period because of a payment failure.

 term_change

term_change_grace_period_ended

Piano

Sent when the subscription exits grace period on renewal/billing attempt, grace period expiration or subscription cancellation.

 term_changed

term_change

You or User

Deprecated. Please useterm_change_scheduled and term_change_finished events of the term_change webhook type instead. Sent when a user initiates their subscription upgrade or when you upgrade a user's subscription.

term_change_finished

term_change_finished

Piano

Deprecated. Please useterm_change_finished event of the term_change webhook type instead. Sent on the day of the actual upgrade.

type

string

webhook type: term_change

version

string

2

typeTitle

string

webhook type title: Upgrade

event

string

event:

• term_change_scheduled

• term_change_finished

• term_change_canceled

• term_change_suspended

• term_change_resumed

• term_change_aborted

• term_change_failure

• term_change_grace_period_started

• term_change_grace_period_ended

eventTitle

string

event title:

• Upgrade scheduled: for term_change_scheduled event

• Upgrade finished: for term_change_finished event

• Upgrade canceled: for term_change_canceled event

• Upgrade suspended: for term_change_suspended event

• Upgrade resumed: for term_change_resumed event

• Upgrade aborted: for term_change_aborted event

• Upgrade failure: for term_change_failure event

• Upgrade grace period started: for term_change_grace_period_started event

• Upgrade grace period ended: for term_change_grace_period_ended event

aid

string

application id

uid

string

end-user id

user_email

string

end-user’s email address

previous_term_id

string

termFROM id

previous_term_name

string

termFROM name

previous_subscription_id

string

subscriptionFROM id

previous_subscription_rid

string

resourceFROM id

previous_subscription_access_id

string

accessFROM id

previous_billing_plan

string

billing plan of the last period of subscriptionFROM:

• <billing plan of the last active access period of subscriptionFROM = AP with id from previous_access_period_id>: for dynamic subscription

• <full billing plan of the payment subscriptionFROM>: for recurring payment subscription with or without trial; same value for the full life of the subscription

previous_access_period_id

string

access period id of the last period of subscriptionFROM:

• <access period id>: for dynamic subscriptionFROM

• null: for recurring subscriptionFROM

new_term_id

string

termTO id

new_term_name

string

termTO name

new_subscription_id

string

subscriptionTO id

new_subscription_rid

string

resourceTO id

new_subscription_access_id

string

accessTO id

new_billing_plan

string

billing plan of the first period of subscriptionTO (period, purchased on upgrade):

• <billing plan of the access period purchased on upgrade = AP with id from new_subscription_access_id>: for dynamic subscription

• <full billing plan of the payment subscriptionTO>: for recurring payment subscription with or without trial; same value for the full life of the subscription

new_access_period_id

string

access period id of the first period of subscriptionTO (period, purchased on upgrade):

• <access period id>: for dynamic subscriptionTO

• null: for recurring subscriptionTO

new_subscription_next_bill_date

long

the value of the “next billing date” field of the subscriptionTO (not null):

• <next auto-renewal of the subscriptionTO> (date in the future): for active subscriptionTO for which auto-renewal is expected

• <last auto-renewal/purchase date of the subscriptionTO> (date in the past): for inactive subscriptionTO or for active subscriptionTO that normally should not have auto-renewal date, because auto-renewal is not expected (subscription on unlimited period, subscription with disabled auto-renewal, subscription with scheduled upgrade etc.)

• all other values are impossible for this webhook type

date_of_access_change

long

date of actual access change:

• <date of granting temporary access for subscriptionTO = date of pending upgrade scheduling>: for pending upgrades when granting temporary access is configured for upgrade

• <subscriptionTO start date = expected upgrade execution date for pending upgrade = upgrade execution date for immediate upgrade>: for pending upgrades when granting temporary access is not configured for upgrade; for immediate upgrade

date_of_billing_change

long

date of actual billing plan change:

• <expected upgrade execution date>: for the cases of pending upgrade when the actual upgrade is only scheduled

• <subscriptionTO start date = upgrade execution date>: for the cases where the upgrade has been executed and was successful or a grace period was provided

• null: for the cases where the upgrade has been executed and failed without providing a grace period

upi_id

string

id of the renewal payment method associated with the subscriptionTO (same as for subscriptionFROM)

is_in_grace

boolean

shows if the subscriptionTO is currently in grace period:

• true: subscriptionTO is in grace period of any type (for this webhook type only the case of grace period after upgrade failure is suitable)

• false: subscriptionTO is not in grace period of any type

grace_period_start_date

long

grace period start date:

• <date>: for subscriptionTO in a grace period (is_in_grace = true)

• null: for subscriptionTO outside of a grace period (is_in_grace = false)

grace_period_length

int

grace period length in days:

• <days>: for subscriptionTO in a grace period (is_in_grace = true)

• null: for subscriptionTO outside of a grace period (is_in_grace = false)

failure_counter

int

number of payment failures for subscriptionTO:

• 1: for active subscriptionTO in a grace period (is_in_grace = true) after first payment failure - grace period start

• <number of failure> (2, 3, 4… ): for active subscriptionTO in a grace period (is_in_grace = true) after payment failure in the middle of the grace period

• <number of last failure> (1, 2, 3, 4… ): for subscriptionTO that become inactive after being in grace period or after payment failure when grace period could not start

• 0: for active subscriptionTO outside of a grace period (is_in_grace = false) that has been in grace period at least once (this also includes the case of successful end of the grace period); for subscription that become inactive while having 0 as failure_counter value

• null: for active or inactive subscriptionTO outside of a grace period (is_in_grace = false) and never been in grace period

passive_churn_logic_id

string

id of the churn prevention logic:

• <id>: for active subscriptionTO in a grace period (is_in_grace = true) when passive churn prevention feature is enabled; for subscriptionTO that become inactive while being in a grace period (is_in_grace = true) when passive churn prevention feature is enabled

• null: for active or inactive subscriptionTO in grace period or outside of it when passive churn prevention feature is disabled; for active subscriptionTO outside of grace period (is_in_grace = false) when passive churn feature is enabled

decline_reason

string

decline reason for a payment attempt:

• <reason>: for all cases when passive_churn_logic_id has a value

• null: for all cases when passive_churn_logic_id doesn’t have a value

payment_id

string

id of a payment associated with upgrade:

<id>: for term_change_finished (for successfully executed upgrade with payment), term_change_grace_period_ended (for successful grace period end) events

null: for term_change_scheduled, term_change_finished (for successfully executed upgrade without payment/with refund), term_change_canceled, term_change_suspended, term_change_resumed, term_change_aborted, term_change_failure, term_change_grace_period_started, term_change_grace_period_ended (for unsuccessful grace period end without transaction attempt or for unsuccessful grace period end after last transaction attempt) events

changed_by

string

id of a user initiated the upgrade or upgrade related action:

• <end-user’s id>: immediate individual upgrade via MA/onsite successful execution; immediate individual onsite upgrade failure execution with grace start; pending individual upgrade via MA/onsite scheduling; successful grace period end after additional manual attempt via MA; scheduled upgrade suspension via MA; suspended upgrade resumption via MA

• <client user’s id>: immediate individual upgrade via PD/API successful execution; pending individual upgrade via PD/API scheduling; pending bulk upgrade scheduling; successful grace period end after additional manual attempt via PD; scheduled upgrade cancelation via PD

• null: pending individual upgrade scheduled via MA/PD/onsite/API successful execution; pending individual upgrade scheduled via MA/PD/onsite/API failure execution with grace start; pending upgrade scheduled in bulk successful execution; pending upgrade scheduled in bulk failure execution with grace start; additional payment attempts in grace period; successful grace period end after additional automatic attempt; unsuccessful grace period end after last additional automatic attempt; unsuccessful grace period end without transaction attempt - subscriptionTO cancelation, subscriptionTO expiration; suspended upgrade abortion

access_granted

new_purchase

User

Sent when a user makes a purchase where a financial transaction that took place. It will also fire when Print Subscription Confirmation (PSC) is redeemed. For free trials, the payment_verified event is sent instead.

access_granted

payment_verified

User

Sent when a user signs up for a free trial. This event is only sent for free trials where the user will eventually be charged. If the user has a promo code that gives them 100% off of a fixed-time purchase, the free_promo_redemption event is sent instead.

access_granted

term_applied_by_publisher

You

Sent when you create a user's subscription via the dashboard on the user's behalf.

access_granted

payment_verified_by_publisher

You

Sent when end-user is subscribed to a term with a free trial or a free period.

access_granted

subscription_imported

You

Sent when a subscription is created by the import tool used by the Piano support team.

access_granted

free_access_granted

You

Sent when you use the Piano Dashboard to grant a user access.

access_granted

free_promo_redemption

User

Sent when a user redeems a promo code for 100% off of a fixed-time purchase. If a user redeems a promo code where there is a transaction that takes place (or will take place in the case of a free trial), either the new_purchase or payment_verified events are sent instead.

access_granted

psc_purchase

User

Sent when a user is granted access after providing their address information on your website for the purpose of the PSC.

access_granted

cross_app_access_granted

Piano

Sent when cross app access has been granted.

access_granted

new_registration_conversion

User

Sent when a user is granted access in return for registering on your website.

access_granted

new_custom_term_conversion

You

Sent when a user converts on a custom term.

access_granted

new_site_license_conversion

User

Sent when a user redeems access under site license.

access_granted

term_change_finished

You, or User, or Piano

Sent upon a successful subscription upgrade.
Triggered for accessTO (or PARENT accessTO if shared).

access_granted

term_change_grace_period_started

Piano

Sent when an upgrade was executed, but the newly created subscription for the new term entered a grace period because of a payment failure.
Triggered for accessTO (or PARENT accessTO if shared).

type

string

webhook type: access_granted

version

string

2

typeTitle

string

webhook type title: Access granted

event

string

event:

• new_purchase

• payment_verified

• term_applied_by_publisher

• payment_verified_by_publisher

• subscription_imported

• free_access_granted

• free_promo_redemption

• psc_purchase

• cross_app_access_granted

• new_registration_conversion

• new_custom_term_conversion

• new_site_license_conversion

• term_change_finished

• term_change_grace_period_started

eventTitle

string

event title:

• New purchase: for new_purchase event

• No payment purchase: for payment_verified event

• New purchase by publisher: for term_applied_by_publisher event

• No payment purchase by publisher: for payment_verified_by_publisher event

• Subscription imported: for subscription_imported event

• Granted free access: for free_access_granted event

• Redemption of free promotion: for free_promo_redemption event

• PSC purchase: for psc_purchase event

• Cross app access granted: for cross_app_access_granted event

• User converted with new registration: for new_registration_conversion event

• User converted custom term: for new_custom_term_conversion event

• New site license conversion: for new_site_license_conversion event

• Upgrade finished: for term_change_finished event

• Upgrade grace period started: for term_change_grace_period_started event

aid

string

application id

expires

long

access expiration date:

• <access expiration date-time>: for access that has a fixed end date

• null: for unlimited access

• all other values are impossible for this webhook type

term_id

string

term id:

• <term id>: for access granted on purchase of dynamic/any payment/any gift/any external/registration/custom/linked term, or for access granted on import of dynamic/recurring payment subscription, or for granted cross app access

• <termTO id>: for access to subscriptionTO granted on successful immediate/pending upgrade execution, or for access to subscriptionTO granted on immediate/pending upgrade execution with grace period start

• null: for access granted on redemption of SEA/ED contract, or for manually/automatically granted free access

uid

string

end-user id

rid

string

resource id

access_id

string

access id

user_email

string

end-user's email address

contract_id

string

contract id:

• <contract id>: for access granted on redemption of SEA/ED contract

• null: for access granted on purchase of dynamic/any payment/any gift/any external/registration/custom/linked term, or for access granted on import of dynamic/recurring payment subscription, or for manually/automatically granted free access, or for granted cross app access, or for access to subscriptionTO granted on successful immediate/pending upgrade execution, or for access to subscriptionTO granted on immediate/pending upgrade execution with grace period start

payment_id

string

user payment id:

• <user payment id>: for access granted on purchase of dynamic/any payment/any gift term with payment, or for access to subscriptionTO granted on successful immediate upgrade execution with payment

• null: for access that granted on purchase of dynamic/any payment/any gift term without payment, or for access granted on import of dynamic/recurring payment subscription, or for access granted on purchase of any external/registration/custom/linked term, or for access granted on redemption of SEA/ED contract, or for manually/automatically granted free access, or for granted cross app access, or for access to subscriptionTO granted on successful immediate upgrade execution without payment, or for access to subscriptionTO granted on successful pending upgrade execution, or for access to subscriptionTO granted on immediate/pending upgrade execution with grace period start

conversion_id

string

conversion id:

• <conversion id>: for access granted on purchase of external term (CDS, Apple iTunes, Google/SwG or Newscycle), or for access granted on import of non-external subscription, or for access granted on redemption of SEA/ED contract

• null: for access granted on purchase of non-external term, or for access to subscriptionTO granted on immediate/pending upgrade execution, or for manually/automatically granted free access, or for granted cross app access

access_modified

subscription_activated

Piano

Sent when an access is modified after a subscription with a future start date is activated.

access_modified

subscription_auto_renewed

Piano

Sent when an access is modified after Piano's system successfully auto-renews a user's subscription. In case of a payment failure upon the auto-renewal, the webhook grace_period_extension_on_renewal is sent instead.

access_modified

subscription_manually_renewed

User

Sent when an access is modified after a user manually renews a subscription, or when you manually renew a user's subscription on the user's behalf.

access_modified

grace_period_extension_on_renewal

Piano

Sent when an access is modified after the Piano system grants additional days of access to a user whose subscription Piano is unable to automatically renew. After the grace period is over, we send the subscription_auto_renewed_failure event.

access_modified

subscription_deferred_canceled

You or User

Sent when an access is modified after a dynamic subscription is canceled and it modifies a user's access.

access_modified

subscription_resumed

You or User

Sent when an access is modified after a dynamic subscription is resumed and a user's access is extended.

access_modified

subscription_updated

You or User

Sent when an access is modified after you update the next bill date on a user's subscription or when a user's subscription is cancelled due to disabling their account.

access_modified

subscription_dynamic_unlimited_period_converted

You

Sent when an access is modified after a dynamic subscription's unlimited period is converted to a period of another type. The action is initiated by You, but done asynchronously.

access_modified

access_modified

You or User

Sent when an access is modified after you modify a user's non-subscription-based access. The access associated with the subscription is modified by updating the next bill date which triggers the subscription_updated event. This webhook also fires when a custom term's access is extended.

This webhook is also sent when a user requests an upgrade and their new access takes effect.

access_modified

cross_app_access_modified

Piano

Sent when a cross app access is modified.

access_modified

site_license_renewed

Piano

Sent when an access is modified after a site license is renewed.

type

string

webhook type: access_modified

version

string

2

typeTitle

string

webhook type title: Access modified

event

string

event:

• subscription_activated

• subscription_auto_renewed

• subscription_manually_renewed*

• grace_period_extension_on_renewal

• subscription_deferred_canceled

• subscription_resumed

• subscription_updated

• subscription_dynamic_unlimited_period_converted

• access_modified

• cross_app_access_modified

• site_license_renewed

eventTitle

string

event title:

• Subscription_activated: for subscription_activated event

• Subscription was automatically renewed: for subscription_auto_renewed event

• Subscription was manually renewed by user: for subscription_manually_renewed event

• Grace period was extended: for grace_period_extension_on_renewal event

• Subscription canceled (deferred cancel): for subscription_deferred_canceled event

• Subscription resumed: for subscription_resumed event

• Subscription updated: for subscription_updated event

• Subscription unlimited period converted: for subscription_dynamic_unlimited_period_converted event

• Access modified: for access_modified event

• Cross app access modified: for cross_app_access_modified

• Site license renewed: for site_license_renewed event

aid

string

application id

expires

long

access expiration date:

• <access expiration date-time>: for access that has a fixed end date

• null: for unlimited access

• all other values are impossible for this webhook type

term_id

string

term id:

• <term id>: for access modified on activation of dynamic/recurring payment subscription, or for access modified on successful manual/automatic renewal of dynamic/recurring payment/any external subscription, or for access modified on renewal with grace period start for dynamic/recurring payment subscription, or for access modified on deferred cancellation of dynamic subscription, or for access modified on resumption of cancelled dynamic subscription, or for access modified after manual change of next billing date for recurring payment subscription, for access modified after converting an unlimited access period of dynamic term, or for modified cross app access

• null: for access modified on renewal of subscription associated with redeemed SEA/ED contract

uid

string

end-user id

rid

string

resource id

access_id

string

access id

user_email

string

end-user's email address

contract_id

string

contract id:

• <contract id>: for access modified on renewal of subscription associated with redeemed SEA/ED contract

• null: for access modified on activation of dynamic/recurring payment subscription, or for access modified on successful manual/automatic renewal of dynamic/recurring payment/any external subscription, or for access modified on renewal with grace period start for dynamic/recurring payment subscription, or for access modified on deferred cancellation of dynamic subscription, or for access modified on resumption of cancelled dynamic subscription, or for access modified after manual change of next billing date for recurring payment subscription, for access modified after converting an unlimited access period of dynamic term, or for modified cross app access

payment_id

string

user payment id:

• <user payment id>: for access modified on successful manual/automatic renewal of dynamic/recurring payment subscription with payment

• null: for access modified on activation of dynamic/recurring payment subscription, for access modified on successful manual/automatic renewal of dynamic/recurring payment subscription without payment, or for access modified on successful renewal of any external subscription, for access modified on renewal of subscription associated with redeemed SEA/ED contract, or for access modified on renewal with grace period start for dynamic/recurring payment subscription, or for access modified on deferred cancellation of dynamic subscription, or for access modified on resumption of cancelled dynamic subscription, or for access modified after manual change of next billing date for recurring payment subscription, for access modified after converting an unlimited access period of dynamic term, or for modified cross app access

conversion_id

string

conversion id:

• <conversion id>: for access modified on renewal of external subscription (CDS, Apple iTunes, Google/SwG or Newscycle), or for access modified on renewal of subscription associated with redeemed SEA/ED contract

• null: for access modified on activation of dynamic/recurring payment subscription, for access modified on renewal of non-external subscription, or for access modified on deferred cancellation of dynamic subscription, or for access modified on resumption of cancelled dynamic subscription, or for access modified after manual change of next billing date for recurring payment subscription, for access modified after converting an unlimited access period of dynamic term, for modified cross app access

access_revoked

access_revoked

You

Sent when a user's access is revoked.

access_revoked

subscription_auto_renewed_failure

Piano

Sent when Piano is unable to charge a user's credit card to renew their subscription, and there is no grace period or the grace period has ended.

access_revoked

access_ended

Piano

Sent when Piano determines that non-subscription-based access has ended. The access_ended event only fires when access “naturally” expires, meaning that it wasn't due to any user, publisher, admin, or Piano action. This event is never sent for access that is associated with subscriptions because subscription_auto_renewed_failure and subscription_expired events will be sent instead.

access_revoked

subscription_canceled

User

Sent when a user cancels their subscription or when you cancel a user's subscription on their behalf.

access_revoked

subscription_expired

Piano

Sent when Piano attempts to renew a user's subscription and determines that auto-renew is turned off.

access_revoked

cross_app_access_revoked

Piano

Sent when cross app access has been revoked.

access_revoked

site_license_expired

Piano

Sent when the end user's site license expires.

access_revoked

site_license_canceled

You

Sent when the end user's site license was canceled.

access_revoked

term_change_finished

You, or User, or Piano

Sent upon a successful upgrade execution.
Triggered for accessFROM (or PARENT accessFROM if shared).

access_revoked

term_change_aborted

Piano

Sent when a pending upgrade is suspended.
Triggered for accessFROM (or PARENT accessFROM if shared).

access_revoked

term_change_failure

Piano

Sent in case of failure on a pending upgrade, with no grace in termTO/periodTO.
Triggered for accessFROM (or PARENT accessFROM if shared).

access_revoked

term_change_grace_period_started

Piano

Sent when an upgrade was executed, but the newly created subscription for the new term entered a grace period because of a payment failure.
Triggered for accessFROM (or PARENT accessFROM if shared).

Field

Type

Value

type

string

webhook type: access_revoked

version

string

2

typeTitle

string

webhook type title: Access revoked

event

string

event:

• access_revoked

• subscription_auto_renewed_failure

• access_ended

• subscription_canceled

• subscription_expired

• cross_app_access_revoked

• site_license_expired

• site_license_canceled

• term_change_finished

• term_change_aborted

• term_change_failure

• term_change_grace_period_started

eventTitle

string

event title:

• Access revoked: for access_revoked event

• Failure of automatic subscription renewal: for subscription_auto_renewed_failure event

• Access ended: for access_ended event

• Subscription canceled (immediate cancel): for subscription_canceled event

• Subscritption expired: for subscription_expired event

• Cross app access revoked: for cross_app_access_revoked event

• Site license expired: for site_license_expired event

• Site license canceled: for site_license_canceled event

• Upgrade finished: for term_change_finished event

• Upgrade aborted: for term_change_aborted event

• Upgrade failure: for term_change_failure event

• Upgrade grace period started: for term_change_grace_period_started event

aid

string

application id

expires

long

access expiration date:

• <access expiration date-time>: for expired access of dynamic/payment/gift subscription, or for free access expired on access end date

• <date-time when access was revoked on external provider’s end>: for revoked access of external subscription - where the expiration is managed by third-party providers such as Google or Apple

• -1: for revoked access of dynamic/payment/gift subscription, or for revoked access to SEA/ED contract subscription, or for free access revoked manually

• all other values are impossible for this webhook type

term_id

string

term id:

• <term id>: for access revoked on renewal failure of recurring payment/external subscription, for access revoked on internal/external renewal failure of dynamic subscription, for access revoked on renewal grace period end of dynamic/recurring payment subscription, or for access revoked on immediate recurring payment/dynamic/external subscription cancellation, or for access expired on expiration of dynamic subscription after deferred cancellation, or for access expired on expiration of recurring payment subscription with turned off auto-renewal, or for single payment/registration term access expired at access end date, or for any gift/external/linked term access revoked on subscription expiration, or for revoked cross app access

• <termFROM id>: for access to subscriptionFROM revoked on successful immediate/pending upgrade execution, or for access to subscriptionFROM revoked on immediate/pending upgrade execution with grace period start, or for access to subscriptionFROM revoked on immediate/pending upgrade execution failure, or for access to subscriptionFROM revoked on pending upgrade abortion

• <termTO id>: for access revoked on upgrade grace period end of dynamic/recurring payment subscriptionTO

• null: for access to SEA/ED contract revoked by client user/licensee representative, or for access to SEA/ED contract subscription revoked on subscription cancellation by end-user, or for access to SEA/ED contract expired on scheduled period end date, or for free access expired on access end date, or for free access revoked manually

uid

string

end-user id

rid

string

resource id

access_id

string

access id

user_email

string

end-user’s email address

contract_id

string

contract id:

• <contract id>: for access to SEA/ED contract revoked by client user/licensee representative, or for access to SEA/ED contract subscription revoked on subscription cancellation by end-user, or for access to SEA/ED contract expired on scheduled period end date

• null: for access revoked on renewal failure of recurring payment/external subscription, for access revoked on internal/external renewal failure of dynamic subscription, for access revoked on renewal grace period end of dynamic/recurring payment subscription, or for access revoked on immediate recurring payment/dynamic/external subscription cancellation, or for access expired on expiration of dynamic subscription after deferred cancellation, or for access expired on expiration of recurring payment subscription with turned off auto-renewal, or for single payment/registration term access expired at access end date, or for any gift/external/linked term access revoked on subscription expiration, or for revoked cross app access, or for access to subscriptionFROM revoked on successful immediate/pending upgrade execution, or for access to subscriptionFROM revoked on immediate/pending upgrade execution with grace period start, or for access to subscriptionFROM revoked on immediate/pending upgrade execution failure, or for access to subscriptionFROM revoked on pending upgrade abortion, or for access revoked on upgrade grace period end of dynamic/recurring payment subscriptionTO, or for free access expired on access end date, or for free access revoked manually

Type

Event

Triggered by

Notes

shared_access_granted

shared_subscription_child_access_auto_redeemed

Piano

Sent when a child access is automatically redeemed due to the purchase, import, activation, update, upgrade, or grace period of the parent subscription.

shared_access_granted

shared_subscription_child_access_manually_redeemed

User

Sent when a user manually redeems their child access via a invitation link from email or via MA.

Field

Type

Value

type

string

webhook type: shared_access_granted

version

string

2

typeTitle

string

webhook type title: Shared access granted

event

string

event:

• shared_subscription_child_access_auto_redeemed

• shared_subscription_child_access_manually_redeemed

eventTitle

string

event title:

• Child access auto redeemed: for shared_subscription_child_access_auto_redeemed event

• Child access manually redeemed: for shared_subscription_child_access_manually_redeemed event

aid

string

application id

uid

string

CHILD end-user's id

user_email

string

CHILD end-user’s email address

access_id

string

CHILD access id

expires

long

CHILD access expiration date:

• <CHILD access expiration date-time>: for CHILD access that has a fixed end date

• null: for unlimited CHILD access

• all other values are impossible for this webhook type

term_id

string

term id of PARENT subscription:

• <term id>: for CHILD access granted automatically on purchase of dynamic/recurring payment term, or for CHILD access granted automatically on import of recurring payment subscription, for CHILD access granted automatically on activation of dynamic/recurring payment subscription, or for CHILD access granted on manual access redemption by CHILD end-user

• <termTO id>: for temporary CHILD access granted automatically on pending upgrade scheduling, or for CHILD access to subscriptionTO granted automatically on successful immediate/pending upgrade execution, or for temporary CHILD access granted automatically on pending upgrade resumption, or for CHILD access to subscriptionTO granted automatically on immediate/pending upgrade execution with grace period start

• all other values are impossible for this webhook type

term_type

string

term type of PARENT subscription:

• DYNAMIC: for CHILD access to dynamic subscription

• PAYMENT: for CHILD access to recurring payment subscription

• all other values are impossible for this webhook type

rid

string

resource id

parent_uid

string

PARENT end-user id

parent_subscription_id

string

PARENT subscription id

Type

Event

Triggered by

Notes

shared_access_modified

subscription_auto_renewed

Piano

Sent for a CHILD access modified when the auto-renewal of its PARENT subscription succeeds on the initial attempt.

shared_access_modified

subscription_manually_renewed

You or User

Sent for a CHILD access modified upon a successful manual renewal of the PARENT subscription.

shared_access_modified

subscription_
grace_period_started

Piano

Sent for a CHILD access modified when a grace period is started upon a failed auto-renewal of the PARENT subscription.

shared_access_modified

subscription_deferred_canceled

You or User

Sent for a CHILD access modified upon a deferred cancellation of the PARENT subscription (the subscription doesn't have a scheduled pending upgrade and is not on the last billing period of its access period).

shared_access_modified

subscription_resumed

You or User

Sent for a CHILD access modified upon a resumption of the PARENT subscription (the subscription doesn't have a scheduled pending upgrade and is not on the last billing period of its access period).

shared_access_modified

subscription_next_bill_date_updated

You

Sent for a CHILD access modified upon an update of the next billing period of the PARENT subscription via the Dashboard or API.

shared_access_modified

subscription_dynamic_unlimited_period_converted

You

Sent for a CHILD access modified upon a conversion of an unlimited access period for a dynamic term when the PARENT subscription is active on this period.

Field

Type

Value

type

string

webhook type: shared_access_modified

version

string

2

typeTitle

string

webhook type title: Shared access modified

event

string

event:

• subscription_auto_renewed

• subscription_manually_renewed

• subscription_grace_period_started

• subscription_deferred_canceled

• subscription_resumed

• subscription_next_bill_date_updated

• subscription_dynamic_unlimited_period_converted

eventTitle

string

event title:

• Subscription was automatically renewed: for subscription_auto_renewed event

• Subscription was manually renewed by user: for subscription_manually_renewed event

• Subscription renewal grace period started: for subscription_grace_period_started event

• Subscription canceled (deferred cancel): for subscription_deferred_canceled event

• Subscription resumed: for subscription_resumed event

• Subscription next bill date updated: for subscription_next_bill_date_updated event

• Subscription unlimited period converted: for subscription_dynamic_unlimited_period_converted event

aid

string

application id

uid

string

CHILD end-user id

user_email

string

CHILD end-user’s email address

access_id

string

CHILD access id

expires

long

CHILD access expiration date:

• <CHILD access expiration date-time>: for CHILD access that has a fixed end date

• null: for unlimited CHILD access

• all other values are impossible for this webhook type

term_id

string

term id of PARENT subscription:

• <term id>: for CHILD access modified on successful manual/automatic renewal of dynamic/recurring payment subscription, or for CHILD access modified on renewal with grace period start for dynamic/recurring payment subscription, or for CHILD access modified on deferred cancellation of dynamic subscription, or for CHILD access modified on resumption of cancelled dynamic subscription, or for CHILD access modified after manual change of next billing date for recurring payment subscription, for CHILD access modified after converting an unlimited access period of dynamic term

• all other values are impossible for this webhook type

term_type

string

term type of PARENT subscription:

• DYNAMIC: for CHILD access to dynamic subscription

• PAYMENT: for CHILD access to recurring payment subscription

• all other values are impossible for this webhook type

rid

string

resource id

parent_uid

string

PARENT end-user id

parent_subscription_id

string

PARENT subscription id

Type

Event

Triggered by

Notes

shared_access_
revoked

shared_subscription_child_access_revoked

You,
or User,
or Piano

Sent when a parent user removes a child user from the list of shared accounts or when you do it via API or the dashboard on the parent user's behalf.

shared_access_
revoked

shared_subscription_child_left

You or User

Sent when a child user manually revokes their child access or when you do it via API on the child user's behalf.

shared_access_
revoked

subscription_canceled

You or User

Sent when a user cancels their subscription or when you cancel a user's subscription on their behalf. Triggered for CHILD accounts with redeemed access.

shared_access_
revoked

subscription_expired

Piano

Sent when a subscription renewal has failed and there is no grace period configured, or when a subscription has been canceled and will not renew, or when there's no next access period configured in the term for this subscription.

shared_access_
revoked

term_change_finished

You,
or User,
or Piano

Sent when a subscription is successfully upgraded.  Triggered for a CHILD account with redeemed access to the termFROM, when such a CHILD is being removed from the list of shared accounts.

shared_access_
revoked

term_change_aborted

Piano

Sent when a pending upgrade is suspended.

Triggered for a CHILD account with redeemed access to the termFROM, when such a CHILD is being removed from the list of shared accounts.

shared_access_
revoked

term_change_failure

Piano

Sent in case of failure on a pending upgrade, with no grace in termTO/periodTO.

Triggered for a CHILD account with redeemed access to the termFROM, when such a CHILD is being removed from the list of shared accounts.

shared_access_
revoked

term_change_grace_period_started

Piano

Sent when an upgrade was executed, but the newly created subscription for the new term entered a grace period because of the payment failure.

Triggered for a CHILD account with redeemed access to the termFROM, when such a CHILD is being removed from the list of shared accounts.

Field

Type

Value

type

string

webhook type: shared_access_revoked

version

string

2

typeTitle

string

webhook type title: Shared access revoked

event

string

event:

• shared_subscription_child_access_revoked

• shared_subscription_child_left

• subscription_canceled

• subscription_expired

• term_change_finished

• term_change_aborted

• term_change_failure

• term_change_grace_period_started

eventTitle

string

event title:

• Child access revoked: for shared_subscription_child_access_revoked event

• Child left: for shared_subscription_child_left event

• Subscription canceled (immediate cancel): for subscription_canceled event

• Subscription expired: for subscription_expired event

• Upgrade finished: for term_change_finished event

• Upgrade aborted: for term_change_aborted event

• Upgrade failure: for term_change_failure event

• Upgrade grace period started: for term_change_grace_period_started event

aid

string

application id

uid

string

CHILD end-user id

user_email

string

CHILD end-user’s email address

access_id

string

CHILD access id

expires

long

CHILD access expiration date:

• <CHILD access expiration date-time>: for expired CHILD access

• -1: for revoked CHILD access

• all other values are impossible for this webhook type

term_id

string

term id of PARENT subscription:

• <term id>: for CHILD access revoked on renewal failure of recurring payment subscription, for CHILD access revoked on internal/external renewal failure of dynamic subscription, for CHILD access revoked on renewal grace period end of dynamic/recurring payment subscription, or for CHILD access revoked on immediate recurring payment/dynamic subscription cancellation, or for CHILD access expired on expiration of dynamic subscription after deferred cancellation, or for CHILD access expired on expiration of recurring payment subscription with turned off auto-renewal

• <termFROM id>: for CHILD access to subscriptionFROM revoked on successful immediate/pending upgrade execution, or for CHILD access to subscriptionFROM revoked on immediate/pending upgrade execution with grace period start, or for CHILD access to subscriptionFROM revoked on immediate/pending upgrade execution failure, or for CHILD access to subscriptionFROM revoked on pending upgrade abortion

• <termTO id>: for CHILD access revoked on upgrade grace period end of dynamic/recurring payment subscriptionTO

• all other values are impossible for this webhook type

term_type

string

term type of PARENT subscription:

• DYNAMIC: for CHILD access to dynamic subscription

• PAYMENT: for CHILD access to recurring payment subscription

• all other values are impossible for this webhook type

rid

string

resource id

parent_uid

string

PARENT end-user id

parent_subscription_id

string

PARENT subscription id

voucher_purchased

voucher_purchase

User

Sent when a user converts on a gift offer and purchases a voucher.

voucher_delivered

voucher_delivery

Piano

Sent when the gift is successfully delivered to the recipient after the voucher has been purchased.

voucher_redeemed

to_giftee_voucher_redeemed

User

Sent when gift recipient redeems their gift and begins their period of access.

access_granted

free_access_granted

Piano

Sent when access to the resource is triggered after the gift is redeemed.

voucher_revoked

voucher_revoked

You

Sent when a gift voucher's access has been revoked.

Type

Event

Triggered by

Notes

licensee_created

licensee_created

You

We send this webhook when a new Site license is created.

licensee_updated

licensee_updated

You

We send this webhook when an existing Site license is updated.

contract_created

 contract_created

You

This webhook is sent when an email domain or specific email address contract is created.

contract_updated

contract_updated

You

This webhook is sent when an email domain or specific email address contract is updated.

contract_deleted

contract_deleted

You

This webhook is sent when an email domain or specific email address contract is deleted.

contract_user_created

contract_user_created

You

We send this webhook when a new user is added to a contract.

contract_redeemed

licensee_contract_redeemed

User

We send this webhook when the end-user redeems a site license contract.

contract_renewed

licensee_contract_auto_renewed

Piano

We send this webhook when the end user's site license contract is renewed.

contract_user_

access_revoked

licensee_contract_subscription_canceled

You

We send this webhook when the end user's site license contract access is revoked.

contract_user_

access_expired

licensee_contract_access_expired

Piano

We send this webhook when the end user's site license contract access expires.

licensee_invite_

to_contract

 licensee_invite_to_contract

 You

We send this webhook when the end-user is invited to a site license contract.

user_created

user_created

You or User

Sent when a user is created through registration or by the publisher dashboard. User creation events include user registration, passwordless registration (single and non-single step), social registration. On your side, events include creating new users via the 'Add new user' button, and bulk creation of users through email or import.

user_updated

user_updated

You or User

Sent when an end user, you, or file import updates the first name, last name, or email fields in the My Account page.

user_updated

piano_id_user_custom_fields_updated

You or User

 Sent when you or the end user updates a custom field. Note that this does not include consent field updates.

user_updated

 piano_id_user_password_updated

User

Sent when the user updates their password through My Account or they reset their password through the email link. Note that a publisher user can trigger the reset password action, but only an end user can complete it.

user_disabled

user_disabled

You or User

Sent when you or the user disable their accounts or their account is disabled via the publisher dashboard.

user_email_confirmed

piano_id_user_email_confirmed

User

Sent when the user confirms their email through double opt-in.

Type

Event

Triggered by

Notes

address_updated

address_updated

You or User

We send this webhook when the end-user updates their delivery address associated with a subscription or a voucher in My Account, or when the delivery address associated with one or several subscriptions or vouchers is updated in publisher dashboard.

user_address_updated

user_address_updated

User

Deprecated. Please use address_updated instead. We send this webhook when end-user updates their delivery address in My Account

Type

Event

Triggered by

Notes

user_payment-method

user_payment-method_new

User

We send this webhook when a user creates a new payment method.

user_payment-method

user_payment-method_update

User

We send this webhook when a user updates the existing payment method or changes the payment method associated with a subscription.

payment_completed

payment_completed

Piano

Sent when the user payment status has been changed to Completed.

payment_failed

payment_failed

Piano

Sent when the user payment fails, is canceled or aborted.

payment_initiated

payment_initiated

Piano

Sent when the user payment has been created in the Initiated status.

payment_pending

payment_pending

Piano

Sent when the user payment status has been changed to Pending.

payment_refund

purchase_refund

You or User

Sent when a full or partial refund has been issued.

type

Required

string

webhook type:

• payment_completed

• payment_failed

• payment_initiated

• payment_pending

typeTitle

Required

string

webhook type title:

• Payment completed

• Payment failed

• Payment initiated

• Payment pending

event

Required

string

Webhook event:

• payment_completed

• payment_failed

• payment_initiated

• payment_pending

eventTitle

Required

string

webhook event title:

• Payment completed

• Payment failed

• Payment initiated

• Payment pending

triggeredBy

Required

string

The type of payment trigger. Possible values:

• new_purchase:

  • purchase in the checkout with new payment method

  • purchase in the checkout with a stored payment method

  • purchase in the ATW with new payment method

  • purchase in the ATW with a stored payment method

• renewal:

  • auto-renewal

  • manual renewal from the checkout

  • manual renewal from the My Account

  • manual renewal from the Publisher dashboard

  • any upgrade from the checkout

  • any upgrade from the My Account

  • any upgrade from the Publisher dashboard

• early_billing:

  • renewal with early billing

version

Required

number

2

userPaymentId

Required

string

The user-payment ID in Piano.

status

Required

string

The user payment status.

statusValue

Required

string

The user payment status value.

amount

Optional

number

The amount from userPayment that has been actually charged.

userPaymentInfoId

Optional

string

The UPI ID in Piano.

externalPaymentId

Optional

string

The external UPI token.

xternalCustomerId

Optional

string

The external customer Id = payment_method_token (for imports)

aId

Required

string

The Piano application ID where the payment has been initiated.

uId

Required

string

The internal user ID in Piano.

termId

Required

string

The Piano term ID that has been purchased.

resourseId

Required

string

The Piano resource ID that is represented with the purchased term.

subscriptionId

Optional

string

The Piano subscription ID that has been created as a result of the purchase or the payment has been made. The parameter could be specified for MITs only.

accessId

Optional

string

The Piano access ID that has been created. The parameter could be specified for MITs only.

billingPeriodDateFrom

Optional

string

The start date of the subscription billing period that is paid with current user payment. The parameter could be specified for MITs only.

billingPeriodDateTo

Optional

string

The end date of the subscription billing period that is paid with the current user payment. The parameter could be specified for MITs only.

merchantID

Optional

string

Merchant ID from External provider configuration.

paymentMethodKey

Optional

string

The value that represents the payment method that should be displayed in the External payment page after the end-user is redirected from Piano. Could be used in cases when there are multiple external payment method configurations for a single merchant.

sourceInt

Required

number

Internal Piano identifier of the payment method.

Type

Event

Triggered by

Notes

subscription_auto_renew_changed

subscription_auto_renew_changed_by_end_user

User

We send this webhook when the end-user interacts with the Auto-renew toggle in My Account.

Deprecated. Instead, please use the subscription_auto_renew_disabled and subscription_auto_renew_enabled events of the subscription_updated webhook type.

Type

Event

Triggered by

Notes

shared_subscription_
child

shared_subscription_child

User

Sent when a child user redeems their shared subscription access via My Account.

Deprecated. Instead, please use the shared_subscription_child_access_auto_redeemed and shared_subscription_child_access_manually_redeemed events of the shared_access_granted webhook type.