Skip to main content
Use the Usage-based Billing webhooks to receive real-time notifications about billing events in your application. These webhooks provide automatic updates for subscription alerts, wallet lifecycle events, transaction status changes, invoice events, credit note events, and subscription lifecycle changes.

​
Subscription alerts

This webhook notifies you when subscription usage thresholds are crossed:
EventTriggerAlternate method for polling
USAGE-BILLING.SUBSCRIPTION-ALERT.TRIGGEREDA threshold defined in an alert was crossed during usage evaluation.Use Get customer current usage to review current and previous usage values. Implement business logic such as notifications, usage caps, or billing adjustments based on the crossed thresholds.

​
Wallet events

These webhooks provide updates on wallet lifecycle and balance changes:
EventTriggerAlternate method for polling
USAGE-BILLING.WALLET.CREATEDA new wallet was successfully created for a customer.Use Show wallet details to retrieve the full wallet configuration. Update your internal systems to track the new wallet and notify the customer of successful setup.
USAGE-BILLING.WALLET.UPDATEDAn existing wallet’s configuration or status was modified.Call Show wallet details to get the updated wallet information. Sync changes with your system and notify stakeholders of wallet modifications.
USAGE-BILLING.WALLET.TERMINATEDA wallet was terminated and is no longer active.Retrieve final wallet state via Show wallet details. Process any remaining balance, update customer records, and trigger cleanup workflows for the terminated wallet.
USAGE-BILLING.WALLET.NET-BALANCE-DEPLETEDThe wallet’s net balance has reached zero or below the usable threshold.Use Show wallet details to check current balance and usage. Implement automatic top-up logic, notify customers of low balance, or suspend services if required by your business logic.

​
Wallet transaction events

These webhooks track wallet state changes when transactions occur. The webhook returns the complete wallet object with updated balances:
EventTriggerAlternate method for polling
USAGE-BILLING.WALLET-TRANSACTION.CREATEDA new transaction was created in the wallet — funds were debited or credited. Returns the updated wallet state.Use Show wallet details to view updated balance and transaction history. Update usage tracking, trigger billing events, or notify customers of transaction activity.
USAGE-BILLING.WALLET-TRANSACTION.UPDATEDAn existing wallet transaction was modified or its status changed. Returns the updated wallet state.Call Show wallet details to get the latest transaction status. Reconcile any changes in your system and update customer billing records accordingly.

​
Invoice events

These webhooks notify you about invoice lifecycle and payment status changes:
EventTriggerAlternate method for polling
USAGE-BILLING.INVOICE.CREATEDA new invoice was generated for a customer.Use Get invoice by ID to retrieve the full invoice details. Send invoice notifications to customers and update your accounting records.
USAGE-BILLING.INVOICE.PAYMENT.OVERDUEAn invoice payment is past due.Call Get invoice by ID to check payment status. Trigger dunning workflows, send payment reminders, or apply late fees according to your business policies.
USAGE-BILLING.INVOICE.PAYMENT.SUCCEEDEDPayment for an invoice was successfully processed.Use Get invoice by ID to confirm payment details. Update accounting records, send payment confirmations, and ensure service continuity.
USAGE-BILLING.INVOICE.PAYMENT.FAILEDAn invoice payment attempt failed.Retrieve invoice details via Get invoice by ID. Notify customers of payment failure, attempt retry using Retry invoice payment, or update payment methods.

​
Credit note events

These webhooks track credit note creation and refund status:
EventTriggerAlternate method for polling
USAGE-BILLING.CREDIT-NOTE.CREATEDA credit note was issued for a customer.Use Get credit note by ID to retrieve credit note details. Apply credits to customer accounts, update billing records, and notify customers of available credits.
USAGE-BILLING.CREDIT-NOTE.REFUND.FAILEDA refund attempt for a credit note failed.Call Get credit note by ID to review credit note status. Investigate refund failure reasons, retry refund processing, or contact customer for alternative refund methods.

​
Subscription lifecycle events

These webhooks provide updates on subscription status changes:
EventTriggerAlternate method for polling
USAGE-BILLING.SUBSCRIPTION.UPDATEDA subscription’s configuration or status was modified.Use Get subscription by ID to retrieve updated subscription details. Sync changes with your system and notify customers of subscription modifications.
USAGE-BILLING.SUBSCRIPTION.TERMINATEDA subscription was cancelled or terminated.Call Get subscription by ID to get final subscription state. Process final billing, revoke access to services, and trigger offboarding workflows.
USAGE-BILLING.SUBSCRIPTION.TRIAL.ENDEDA subscription’s trial period has ended.Retrieve subscription details via Get subscription by ID. Begin regular billing cycles, notify customers of trial expiration, and confirm payment method availability.

​
Handle webhook events

To handle webhook events:
  1. Review the list of webhook events for Usage-based Billing and select the events for your app to subscribe.
  2. Subscribe to the selected webhook events through one of the following means:
  • PayPal developer account: Log in to your account, go to App details page > Features > Webhooks, and subscribe to webhook events.
  • Webhooks management API.
  1. In your server-side app code, define a webhook handler that:
For more information, see Webhooks overview and Webhooks integration guide.

​
Sample webhook payloads

Webhook notifications include the event type, resource information, and HATEOAS links. The following examples show the payload structure for different webhook events:
Note: Webhook notifications contain basic event information. Use the HATEOAS links in the webhook response to retrieve detailed resource information. 
{
  "id": "8PT597110X687430LKGECATA",
  "create_time": "2025-05-27T19:26:01Z",
  "event_version": "1.0",
  "summary": "A new alert was triggered",
  "resource_version": "1.0",
  "links": [
    {
      "href": "https://api-m.paypal.com/v1/notifications/webhooks-events/8PT597110X687430LKGECATA",
      "rel": "self",
      "method": "GET"
    }
  ],
  "resource_type": "subscription-alert",
  "event_type": "USAGE-BILLING.SUBSCRIPTION-ALERT.TRIGGERED",
  "resource": {
    "id": "ff604dc4-2223-412a-a8f4-8fde7dfd3346",
    "external_subscription_id": "SUB_1752779018503",
    "metric_code": "Storage_Metrics_1754980238",
    "type": "METRIC_CURRENT_USAGE_UNITS",
    "code": "ALERT_CODE_1234567890",
    "name": "Current Usage Alert for Storage",
    "current_value": 1200,
    "previous_value": 900,
    "crossed_thresholds": [
      {
        "code": "hard",
        "value": "1100",
        "recurring": false
      }
    ],
    "triggered_at": "2025-05-27T19:25:02Z"
  }
}
⌘I