Event reference
164 event types across 40 resource families. Subscribe an endpoint to any subset; an endpoint with no list receives all of them.
customer
The payer's own record: created, changed, archived, and every movement of the promotional or excess credit held against their name.
| Event type | |
|---|---|
customer_created | |
customer_updated | |
customer_archived | |
customer_restored | |
customer_contact_added | |
customer_contact_updated | |
customer_contact_removed | |
customer_shipping_address_added | |
customer_shipping_address_updated | |
customer_shipping_address_archived | |
customer_billing_info_updated | |
customer_promotional_credits_added | |
customer_promotional_credits_deducted | |
customer_excess_payment_recorded | |
customer_credits_restored |
payment_source
A stored instrument belonging to a customer. These are the events that warn you an instrument will stop working before it does — expiry, an insufficient mandate, an outright refusal.
| Event type | |
|---|---|
payment_source_added | |
payment_source_updated | |
payment_source_deleted | |
payment_source_expiring | Sent ahead of the expiry date, while the instrument still works, so you can ask the customer to replace it before a renewal fails. |
payment_source_expiry_reminder | Sent on each lead day before a card expires, when the business sets lead days for card expiry (reminder_config.card_expiring). Carries expires_at and lead_days. Emitted once per card, expiry date and lead day. payment_source_expiring still fires once, when the card enters its expiry month. |
payment_source_mandate_insufficient | The instrument's authorised per-debit ceiling is below the next amount due on a subscription it is attached to. The ceiling is fixed when the instrument is authorised and cannot be raised in place — only a fresh authorisation from the customer replaces it, so this is a prompt to ask for one. |
payment_source_expired | |
payment_source_role_changed | |
payment_source_invalidated | The instrument was refused in a way that will not resolve on its own and has been marked unusable. Distinct from expiry: nothing ran out, it was declined. |
subscription
The life of one subscription, from creation through each renewal to cancellation, including changes scheduled ahead of time and the reminders sent before they take effect.
| Event type | |
|---|---|
subscription_created | |
subscription_started | |
subscription_activated | |
subscription_changed | |
subscription_change_scheduled | |
subscription_scheduled_change_removed | |
subscription_renewed | |
subscription_renewal_skipped | |
subscription_skip_scheduled | |
subscription_scheduled_skip_removed | |
subscription_trial_ending | Sent on each of the business's lead days before a trial ends, with lead_days on the event. |
subscription_cancel_scheduled | |
subscription_scheduled_cancellation_removed | |
subscription_canceled | |
subscription_paused | |
subscription_pause_scheduled | |
subscription_resumed | |
subscription_resumption_scheduled | |
subscription_reactivated | |
subscription_deleted | |
subscription_renewal_reminder | Sent on each of the business's lead days before a renewal (reminder_config), with lead_days on the event. Emitted once per subscription, renewal date and lead day, so it is safe to act on directly. |
subscription_cancellation_reminder | Sent on each of the business's lead days before a scheduled cancellation takes effect, with lead_days on the event. |
subscription_pause_reminder | Sent on each of the business's lead days before a scheduled pause (reminder_config.pause), with pause_at, lead_days and scheduled_change on the event. Off by default. |
subscription_resume_reminder | Sent on each of the business's lead days before a scheduled resume (reminder_config.resume), with resume_at, lead_days and scheduled_change on the event. Off by default. |
subscription_pre_debit_notification | Advance notice of a mandate debit, carrying the amount, the date and the mandate reference. Required before every debit on some rails, and sent by the platform because the gateway does not send it. |
invoice
An invoice's progress from generated to paid, written off or voided, together with the dunning sequence that chases an unpaid one.
| Event type | |
|---|---|
invoice_generated | |
invoice_pending_created | |
invoice_closed | |
invoice_updated | |
invoice_paid | |
invoice_payment_due | |
invoice_payment_due_reminder | Sent on each of the business's lead days before the due date of an open invoice that is not collected automatically (reminder_config.payment_due), with due_at and lead_days on the event. Off by default. |
invoice_not_paid | |
invoice_voided | |
invoice_written_off | |
invoice_deleted | |
invoice_dunning_started | |
invoice_dunning_exhausted | The retry sequence for an unpaid invoice has run out of attempts. No further collection will be tried automatically. |
invoice_dunning_stopped | |
invoice_dunning_reminder |
credit_note
Credit issued against an invoice, and what became of it — applied to a balance, refunded to the payer, or voided.
| Event type | |
|---|---|
credit_note_created | |
credit_note_allocated | |
credit_note_refunded | |
credit_note_refund_reversed | |
credit_note_voided |
payment
An attempt to collect money and how it ended. payment_authentication_required is the one outcome that is neither success nor failure.
| Event type | |
|---|---|
payment_initiated | |
payment_succeeded | |
payment_failed | |
payment_authentication_required | The debit was accepted but the rail has paused it pending the buyer's additional authentication. Neither a success nor a failure: the money moves only if the buyer authenticates, and nothing else will prompt them. |
refund
Money on its way back to the payer, reported twice: once when accepted, once when settled.
| Event type | |
|---|---|
refund_created | The provider has ACCEPTED the refund. On cards and bank rails the money lands days later, so treat this as an instruction in flight rather than an outcome. |
refund_settled | The refund actually went through, confirmed by the provider. This is the one to pay out or notify on. |
refund_failed |
transaction
A recorded movement of money that needs your attention, has been reconciled, or failed after it appeared to succeed.
| Event type | |
|---|---|
transaction_needs_attention | |
transaction_reconciled | |
transaction_late_failure | A transaction that had been reported as successful was later reversed by the provider. |
dispute
A chargeback opened by the payer's bank or card network, the money moving out and possibly back, and the case closing.
| Event type | |
|---|---|
dispute_created | |
dispute_funds_withdrawn | |
dispute_funds_reinstated | |
dispute_won | |
dispute_lost | |
dispute_closed |
gateway_account
A payment gateway connection on one of your businesses being added, changed or removed.
| Event type | |
|---|---|
gateway_account_created | |
gateway_account_updated | |
gateway_account_deleted |
payment_intent
A container for attempts at the gateway — either authorising a charge to capture later, or a zero-amount authorisation whose product is a stored instrument.
| Event type | |
|---|---|
payment_intent_created | |
payment_intent_authorized | |
payment_intent_expired | |
payment_intent_consumed | |
payment_intent_failed | |
payment_intent_voided |
payment_attempt
One individual try against the gateway inside an intent. A buyer who fails authentication twice before succeeding leaves three attempts, and none overwrite the earlier ones.
| Event type | |
|---|---|
payment_attempt_created | |
payment_attempt_failed |
wallet
Prepaid credit added to a customer's wallet.
| Event type | |
|---|---|
wallet_topped_up |
receipt
A numbered record of money received: one per payment, or one per payment on a payment request. Sent when the receipt gets its number, which is within seconds of the payment.
| Event type | |
|---|---|
receipt_created | Carries the receipt number, the amount received and what it was applied to. A receipt never changes after this event. |
payment_request
A request for several open invoices of one customer, paid by one charge or one link. Each invoice still gets its own payment and its own payment_succeeded, which names the request.
| Event type | |
|---|---|
payment_request_created | |
payment_request_paid | Every invoice in the request is settled. Sent once, after the child payment_succeeded events. |
payment_request_payment_failed | The charge for the request failed or was reversed. The request is open again and the customer was sent the link. |
payment_request_canceled | |
payment_request_expired |
dunning_policy
A named set of dunning settings that you assign to customers. A customer with no policy uses the business dunning settings.
| Event type | |
|---|---|
dunning_policy_created | |
dunning_policy_updated | |
dunning_policy_archived |
coupon
A discount in your catalogue being created or changed, and applied to or removed from a subscription.
| Event type | |
|---|---|
coupon_created | |
coupon_updated | |
coupon_archived | |
coupon_applied | |
coupon_removed |
coupon_set
A batch of single-use codes for one coupon.
| Event type | |
|---|---|
coupon_set_created | |
coupon_set_codes_added |
coupon_code
An individual code within a set.
| Event type | |
|---|---|
coupon_code_archived |
product_group
A grouping of products in your catalogue.
| Event type | |
|---|---|
product_group_created | |
product_group_updated | |
product_group_archived |
product
A product in your catalogue.
| Event type | |
|---|---|
product_created | |
product_updated | |
product_archived |
price
A price on a product — the amount, currency and billing period a subscription is sold at.
| Event type | |
|---|---|
price_created | |
price_updated | |
price_archived |
attached_item
An add-on or charge attached to a product so it is carried onto subscriptions of that product.
| Event type | |
|---|---|
attached_item_created | |
attached_item_updated | |
attached_item_deleted |
differential_price
A price override that applies to one specific product-and-plan combination.
| Event type | |
|---|---|
differential_price_set | |
differential_price_deleted |
feature
A capability in your catalogue that a plan can grant, such as single sign-on or a project limit. Use these events to refresh any entitlements your app caches.
| Event type | |
|---|---|
feature_created | |
feature_updated | |
feature_archived | The feature no longer grants anything: it leaves every subscription's entitlements and its checks answer feature_archived. Grants are kept, and reactivating the feature sends feature_updated with active: true. |
plan_entitlement
What a product grants for one feature. A change here alters the entitlements of every subscription on that product.
| Event type | |
|---|---|
plan_entitlement_set | Sent when a grant is created or its value changes. The payload carries value and previous_value, which is null for a new grant. |
subscription_entitlement
A per-subscription override of what its plan grants for one feature.
| Event type | |
|---|---|
subscription_entitlement_set | Sent when an override is created or its value changes. The payload carries value and previous_value, which is null for a new override. |
manual_discount
A percentage or fixed-amount discount applied directly to a subscription without a coupon in the catalogue.
| Event type | |
|---|---|
manual_discount_applied | |
manual_discount_removed |
usage
Metered usage recorded against a subscription, which later prices an invoice line.
| Event type | |
|---|---|
usage_recorded |
meter
A meter: what to count from your usage events, and how to add the values up.
| Event type | |
|---|---|
meter_created | |
meter_updated | |
meter_archived |
usage_event
Usage events you sent. We do not send one webhook for each event; this family reports on them in summary.
| Event type | |
|---|---|
usage_event_unmatched | Sent at most once an hour when events arrived with a customer key that no customer has. Add the key to a customer and the events bill. |
model_prices
The AI model price list. Sent when a list price that your meters use changes.
| Event type | |
|---|---|
model_prices_changed | Sent once per price sync to each business whose meters used a changed model in the last 35 days. Each change gives the old and new price, the time the new price starts, and two flags: bill_moves (a live subscription bills that model from the list) and cost_moves (you have no cost of your own for it). Usage before the start time keeps the old price. |
credit_unit
A unit of credit that you define, such as one credit worth USD 0.01.
| Event type | |
|---|---|
credit_unit_created | |
credit_unit_updated | |
credit_unit_archived |
credit_grant
Credit that a customer holds, in money or in your credit unit. Invoices use it in a fixed order, and it can expire.
| Event type | |
|---|---|
credit_grant_created | |
credit_grant_applied | Sent once for each invoice that used credit grants. It lists each grant and the amount that the invoice used. |
credit_grant_expired | |
credit_grant_voided | |
credit_grant_restored | A voided invoice gave its credit back. When the grant had expired, the credit comes back as a new grant that expires in 12 months. |
credit_grant_activated |
credit_hold
An amount of credit that your app reserved before a call. We send these events only to an endpoint that lists them by name.
| Event type | |
|---|---|
credit_hold_created | |
credit_hold_captured | |
credit_hold_released | |
credit_hold_expired |
spend_limit
A spend limit on a customer, a subscription or a usage property. Sent once per limit, subject and interval when spend reaches the limit.
| Event type | |
|---|---|
spend_limit_reached | Carries the limit, the subject, the interval, the amount spent and when the interval resets. mode is hard (new requests are refused) or soft (notice only). |
customer_limit_tier
A limit tier that a customer reached when its total paid amount grew. A tier never goes down after a refund.
| Event type | |
|---|---|
customer_limit_tier_reached |
usage_alert
An alert on usage, spend, credit balance or credit runway. Each threshold triggers at most once per period and resolves once.
| Event type | |
|---|---|
usage_alert_triggered | |
usage_alert_resolved | The value moved back across a threshold, or the period ended (reason: period_ended). Each trigger has exactly one resolve. |
credit_auto_topup
Automatic top-up: credit bought when the balance is low or on a schedule.
| Event type | |
|---|---|
credit_auto_topup_scheduled | |
credit_auto_topup_succeeded | |
credit_auto_topup_failed | |
credit_auto_topup_skipped | |
credit_auto_topup_threshold_low |
usage_threshold
Usage invoiced during the period because the unbilled usage reached the amount that you set.
| Event type | |
|---|---|
usage_threshold_reached |