Skip to content

subscription

POST

Sent when a subscription changes state. Subtypes describe changes across the subscription lifecycle:

  • STARTING_TRIAL - Trial period starts
  • CONVERTION - Trial converts to paid subscription
  • RENEWING - Subscription renews (regular charge)
  • UNSUBSCRIPTION - User cancels subscription (auto-renewal disabled)
  • PLANNING_POSTPONED_SUBSCRIPTION - Subscription with UPCOMING status scheduled to start when delayed_start migration is used
  • PAUSING - Subscription paused
  • DEFERRING - Next charge date postponed
  • RESUMING - Paused subscription resumes
  • RECOVERING_AUTORENEW - Auto-renewal restored after failure
  • EXPIRATION - Subscription expired
  • UNKNOWN - Unknown or unclassified event
  • START_GRACE - Grace period starts after failed charge
  • START_RETRY - Retry attempts start without grace period
  • FINISH_GRACE - Grace period ends
  • RECOVERING - Recovered from grace/retry state
Media typeapplication/json
SubscriptionWebhookPayloadOut
object
event_type
required
NotificationsTypesEnum
string
one of subscription oneoff consumable order refund user dispute
event_id
required
Event Id
string format: uuid
event_timestamp
required
Event Timestamp
string format: date-time
is_livemode
required
Is Livemode
boolean
subtype
required
SubsHistoryEvents
string
one of starting_trial convertion renewing unsubscription planning_postponed_subscription pausing defering resuming recovering_autorenew expiration unknown start_grace start_retry finish_grace recovering
external_id
required
External Id
string
subscription
required
object
Show 16 propertiesHide properties
subs_id
required
Subs Id
string format: uuid
user_uuid
required
User Uuid
string format: uuid
is_active
required
Is Active

Whether premium features are available

boolean
price_point
required
object
Show 13 propertiesHide properties
ident
required
Ident
string
currency
required
object
Show 4 propertiesHide properties
code
required
Code
string
minor_units
required
Minor Units
integer
title
required
Title
string
symbol
required
Symbol
string
intro_type
required
IntroTypeEnum
string
one of no_intro free_trial paid_trial
lifetime_price
Lifetime Price
string
nullable
intro_free_trial_period
integer
nullable
intro_free_trial_period_duration
Any of:
DurationEnum
string
one of minutes days weeks months years
intro_paid_trial_price
Intro Paid Trial Price
string
nullable
intro_paid_trial_period
integer
nullable
intro_paid_trial_period_duration
Any of:
DurationEnum
string
one of minutes days weeks months years
next_price
Next Price
string
nullable
next_period
integer
nullable
next_period_duration
Any of:
DurationEnum
string
one of minutes days weeks months years
features
required
Features

Premium features included

Array<object>
Show 2 propertiesHide properties
ident
required
Ident
string
description
string
nullable
status
required
Status

Subscription status

Array<string>
started_at
required
Started At

When subscription started. For the first billing cycle, this equals current_period_starts_at.

string format: date-time
current_period_starts_at
required
Current Period Starts At

When current billing period starts. May be in the future because we charge users 2 hours in advance.

string format: date-time
current_period_ends_at
required
Current Period Ends At

When current billing period ends. May be in the past if the last charge failed.

string format: date-time
next_check_at
required
string format: date-time
nullable
next_payment_at
string format: date-time
nullable
iteration
required
Iteration

Billing cycle number

integer
available_actions
required
Available Actions

Actions you can perform on this subscription

Array<string>
one of pause resume defer disable_autorenew enable_autorenew create_discount migration
initial_order_metadata
required
object

Custom metadata from the initial order

Show 1 propertyHide property
key
additional properties
any
discounts
required
Discounts

Discounts applied to this subscription

Array<object>
DiscountOut
Show 6 propertiesHide properties
discount_id
required
Discount Id
string format: uuid
subs_id
required
Subs Id
string format: uuid
count_of_iterations
required
integer
nullable
count_of_iterations_available
required
integer
nullable
percent
required
integer
nullable
report
required
object
Report
Show 1 propertyHide property
key
additional properties
string
unused_premium_after_pause
integer
nullable
updated_at
required
Updated At

When the subscription last changed

string format: date-time
user
required
object
Show 3 propertiesHide properties
external_id
required
External Id
string
email
required
Email
string
email_aliases
required
Email Aliases

Previous email addresses associated with this user

Array<string>
order
Any of:
Show 16 propertiesHide properties
order_id
required
Order Id
string format: uuid
amount
required
Amount
string
currency_code
required
Currency Code
string
subs_id
string format: uuid
nullable
oneoff_id
string format: uuid
nullable
external_id
required
External Id
string
user_uuid
required
User Uuid
string format: uuid
initial_order_metadata
required
object
Show 1 propertyHide property
key
additional properties
any
psp
Any of:
PspEnum
string
one of stripe braintree paypal adyen checkout primer_processor airwallex unlimint
psp_store_id

Adyen store that processed the payment, as sent to Primer in ff_adyen_shop_id_<region>. Adyen only reports it in its notification, so it appears once that notification is processed.

string
nullable
psp_transaction_id

The processor’s own ID for the sale that took the payment, as the processor reported it, for example the PaymentIntent ID (pi_...) for Stripe. Never the ID of a refund or a declined attempt. Null while the order isn’t paid (declined, cancelled, or a card check for a trial or card update) or when the processor reported none.

string
nullable
one_click
Any of:

Details of a one-click payment: how it was sent, which saved method was charged, and its 3DS outcome.

Show 7 propertiesHide properties
initiation_type

How the payment was sent to the PSP: cit (customer-initiated, the bank can ask for 3DS) or mit (merchant-initiated).

string
nullable
one of cit mit
one_click_mode

wallet_reauth: the customer confirmed the upsell in the Apple Pay or Google Pay sheet, and it was charged with that fresh wallet token (customer-initiated). Null for a one-click payment charged on the saved method.

string
nullable
one of wallet_reauth
threeds_outcome
Any of:
ThreeDSOutcome
string
one of none pending frictionless challenge_passed challenge_failed frictionless_failed abandoned skipped completed_unknown failed_without_result
threeds_reason_code

The PSP’s raw 3DS reason code for the outcome, for example CARD_AUTHENTICATION_FAILED, TRANSACTION_TIMED_OUT_AT_THE_ACS, or NOT_SUPPORTED_BY_ISSUER. Null when the PSP reported none.

string
nullable
saved_method_type
Any of:
SavedMethodType
string
one of card google_pay_pan_only google_pay_device_token google_pay_unknown apple_pay paypal other
card_network

Card brand of the charged method in upper case, for example VISA or MASTERCARD. Null when unknown and for PSPs other than Primer.

string
nullable
threeds_required

Whether 3DS was required for this payment: true unless threeds_outcome is none or skipped. Null when threeds_outcome is null.

boolean
nullable
retry_step
integer
nullable
created_at
string format: date-time
nullable
decline_reason
Any of:
Show 4 propertiesHide properties
message
required
string
nullable
type
required
string
nullable
code
required
string
nullable
decline_type
required
string
nullable
status
required
OrderStatus
string
one of authorized settling settled declined cancelled success