Webhooks reference - Paypal Docs

Limited Release

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:

Event	Trigger	Alternate method for polling
USAGE-BILLING.SUBSCRIPTION-ALERT.TRIGGERED	A 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:

Event	Trigger	Alternate method for polling
USAGE-BILLING.WALLET.CREATED	A 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.UPDATED	An 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.TERMINATED	A wallet was terminated and is no longer active.	Retrieve final wallet state using Show wallet details. Process any remaining balance, update customer records, and trigger cleanup workflows for the terminated wallet.
USAGE-BILLING.WALLET.NET-BALANCE-DEPLETED	The wallet’s net balance has reached zero or less than 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:

Event	Trigger	Alternate method for polling
USAGE-BILLING.WALLET-TRANSACTION.CREATED	A 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.UPDATED	An 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:

Event	Trigger	Alternate method for polling
USAGE-BILLING.INVOICE.CREATED	A 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.OVERDUE	An 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.SUCCEEDED	Payment 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.FAILED	An invoice payment attempt failed.	Retrieve invoice details using 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:

Event	Trigger	Alternate method for polling
USAGE-BILLING.CREDIT-NOTE.CREATED	A 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.FAILED	A 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:

Event	Trigger	Alternate method for polling
USAGE-BILLING.SUBSCRIPTION.UPDATED	A 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.TERMINATED	A 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.ENDED	A subscription’s trial period has ended.	Retrieve subscription details using 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:

Review the list of webhook events for Usage-based Billing and select the events for your app to subscribe.
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.

In your server-side app code, define a webhook handler that:

Listens to the webhook event.
Confirms receipt of the webhook event to PayPal.
Verifies the source of the event notification.
Performs further actions based on event data.

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:

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"
  }
}

{
  "id": "8PT597110X687430LKGECATA",
  "create_time": "2025-05-27T19:26:01Z",
  "event_version": "1.0",
  "summary": "A new wallet was created",
  "resource_version": "1.0",
  "links": [
    {
      "href": "https://api-m.paypal.com/v1/notifications/webhooks-events/8PT597110X687430LKGECATA",
      "rel": "self",
      "method": "GET"
    }
  ],
  "resource_type": "wallet",
  "event_type": "USAGE-BILLING.WALLET.CREATED",
  "resource": {
    "id": "943254a2-0240-4414-bede-c0d211340c53",
    "external_customer_id": "5eb02857-a71e-4ea2-bcf9-1753842358",
    "status": "ACTIVE",
    "available_balance": {
      "value": 120.35,
      "currency_code": "USD"
    },
    "ongoing_usage": {
      "value": 100.00,
      "currency_code": "USD"
    },
    "net_balance": {
      "value": 20.35,
      "currency_code": "USD"
    },
    "name": "Prepaid Wallet",
    "rate_amount": "1.0",
    "available_credits": "120.35",
    "ongoing_usage_credits": "100.0",
    "net_balance_credits": "20.35",
    "consumed_credits": "0.0",
    "created_at": "2025-07-30T20:13:18Z",
    "expiration_at": "2026-10-08T00:00:00Z",
    "recurring_transaction_rules": [
      {
        "trigger": "INTERVAL",
        "method": "TARGET",
        "interval": "WEEKLY",
        "target_ongoing_balance": "200.0",
        "started_at": "2025-07-01T17:30:15Z",
        "expiration_at": "2026-10-08T00:00:00Z"
      }
    ]
  }
}

{
  "id": "8PT597110X687430LKGECATA",
  "create_time": "2025-05-27T19:26:01Z",
  "event_version": "1.0",
  "summary": "A wallet was updated",
  "resource_version": "1.0",
  "links": [
    {
      "href": "https://api-m.paypal.com/v1/notifications/webhooks-events/8PT597110X687430LKGECATA",
      "rel": "self",
      "method": "GET"
    }
  ],
  "resource_type": "wallet",
  "event_type": "USAGE-BILLING.WALLET.UPDATED",
  "resource": {
    "id": "943254a2-0240-4414-bede-c0d211340c53",
    "external_customer_id": "5eb02857-a71e-4ea2-bcf9-1753842358",
    "status": "ACTIVE",
    "available_balance": {
      "value": 150.00,
      "currency_code": "USD"
    },
    "ongoing_usage": {
      "value": 75.00,
      "currency_code": "USD"
    },
    "net_balance": {
      "value": 75.00,
      "currency_code": "USD"
    },
    "name": "Prepaid Wallet - Updated",
    "rate_amount": "1.0",
    "available_credits": "150.0",
    "ongoing_usage_credits": "75.0",
    "net_balance_credits": "75.0",
    "consumed_credits": "5.0",
    "created_at": "2025-07-30T20:13:18Z",
    "expiration_at": "2026-10-08T00:00:00Z"
  }
}

{
  "id": "8PT597110X687430LKGECATA",
  "create_time": "2025-05-27T19:26:01Z",
  "event_version": "1.0",
  "summary": "A wallet was terminated",
  "resource_version": "1.0",
  "links": [
    {
      "href": "https://api-m.paypal.com/v1/notifications/webhooks-events/8PT597110X687430LKGECATA",
      "rel": "self",
      "method": "GET"
    }
  ],
  "resource_type": "wallet",
  "event_type": "USAGE-BILLING.WALLET.TERMINATED",
  "resource": {
    "id": "943254a2-0240-4414-bede-c0d211340c53",
    "external_customer_id": "5eb02857-a71e-4ea2-bcf9-1753842358",
    "status": "TERMINATED",
    "available_balance": {
      "value": 120.35,
      "currency_code": "USD"
    },
    "ongoing_usage": {
      "value": 0.00,
      "currency_code": "USD"
    },
    "net_balance": {
      "value": 120.35,
      "currency_code": "USD"
    },
    "name": "Prepaid Wallet",
    "rate_amount": "1.0",
    "available_credits": "120.35",
    "ongoing_usage_credits": "0.0",
    "net_balance_credits": "120.35",
    "consumed_credits": "0.0",
    "created_at": "2025-07-30T20:13:18Z",
    "expiration_at": "2026-10-08T00:00:00Z",
    "terminated_at": "2025-05-27T19:25:00Z"
  }
}

{
  "id": "8PT597110X687430LKGECATA",
  "create_time": "2025-05-27T19:26:01Z",
  "event_version": "1.0",
  "summary": "Wallet net balance has been depleted",
  "resource_version": "1.0",
  "links": [
    {
      "href": "https://api-m.paypal.com/v1/notifications/webhooks-events/8PT597110X687430LKGECATA",
      "rel": "self",
      "method": "GET"
    }
  ],
  "resource_type": "wallet",
  "event_type": "USAGE-BILLING.WALLET.NET-BALANCE-DEPLETED",
  "resource": {
    "id": "943254a2-0240-4414-bede-c0d211340c53",
    "external_customer_id": "5eb02857-a71e-4ea2-bcf9-1753842358",
    "status": "ACTIVE",
    "available_balance": {
      "value": 0.00,
      "currency_code": "USD"
    },
    "ongoing_usage": {
      "value": 100.00,
      "currency_code": "USD"
    },
    "net_balance": {
      "value": -100,
      "currency_code": "USD"
    },
    "name": "Prepaid Wallet",
    "rate_amount": "1.0",
    "available_credits": "0.0",
    "ongoing_usage_credits": "100.0",
    "net_balance_credits": "-100.0",
    "consumed_credits": "120.35",
    "created_at": "2025-07-30T20:13:18Z",
    "expiration_at": "2026-10-08T00:00:00Z"
  }
}

{
  "id": "8PT597110X687430LKGECATA",
  "create_time": "2025-05-27T19:26:01Z",
  "event_version": "1.0",
  "summary": "A wallet transaction was created",
  "resource_version": "1.0",
  "links": [
    {
      "href": "https://api-m.paypal.com/v1/notifications/webhooks-events/8PT597110X687430LKGECATA",
      "rel": "self",
      "method": "GET"
    }
  ],
  "resource_type": "wallet-transaction",
  "event_type": "USAGE-BILLING.WALLET-TRANSACTION.CREATED",
  "resource": {
    "id": "943254a2-0240-4414-bede-c0d211340c53",
    "external_customer_id": "5eb02857-a71e-4ea2-bcf9-1753842358",
    "status": "ACTIVE",
    "available_balance": {
      "value": 170.35,
      "currency_code": "USD"
    },
    "ongoing_usage": {
      "value": 100.00,
      "currency_code": "USD"
    },
    "net_balance": {
      "value": 70.35,
      "currency_code": "USD"
    },
    "name": "Prepaid Wallet",
    "rate_amount": "1.0",
    "available_credits": "170.35",
    "ongoing_usage_credits": "100.0",
    "net_balance_credits": "70.35",
    "consumed_credits": "50.0",
    "created_at": "2025-07-30T20:13:18Z",
    "expiration_at": "2026-10-08T00:00:00Z"
  }
}

{
  "id": "8PT597110X687430LKGECATA",
  "create_time": "2025-05-27T19:26:01Z",
  "event_version": "1.0",
  "summary": "A wallet transaction was updated",
  "resource_version": "1.0",
  "links": [
    {
      "href": "https://api-m.paypal.com/v1/notifications/webhooks-events/8PT597110X687430LKGECATA",
      "rel": "self",
      "method": "GET"
    }
  ],
  "resource_type": "wallet-transaction",
  "event_type": "USAGE-BILLING.WALLET-TRANSACTION.UPDATED",
  "resource": {
    "id": "943254a2-0240-4414-bede-c0d211340c53",
    "external_customer_id": "5eb02857-a71e-4ea2-bcf9-1753842358",
    "status": "ACTIVE",
    "available_balance": {
      "value": 145.35,
      "currency_code": "USD"
    },
    "ongoing_usage": {
      "value": 75.00,
      "currency_code": "USD"
    },
    "net_balance": {
      "value": 70.35,
      "currency_code": "USD"
    },
    "name": "Prepaid Wallet",
    "rate_amount": "1.0",
    "available_credits": "145.35",
    "ongoing_usage_credits": "75.0",
    "net_balance_credits": "70.35",
    "consumed_credits": "25.0",
    "created_at": "2025-07-30T20:13:18Z",
    "expiration_at": "2026-10-08T00:00:00Z"
  }
}

{
  "id": "8PT597110X687430LKGECATA",
  "create_time": "2025-05-27T19:26:01Z",
  "event_version": "1.0",
  "summary": "A new invoice was created",
  "resource_version": "1.0",
  "links": [
    {
      "href": "https://api-m.paypal.com/v1/notifications/webhooks-events/8PT597110X687430LKGECATA",
      "rel": "self",
      "method": "GET"
    }
  ],
  "resource_type": "invoice",
  "event_type": "USAGE-BILLING.INVOICE.CREATED",
  "resource": {
    "id": "27986ceb-bb27-461d-82b1-f044646e192d",
    "sequential_id": 5,
    "status": "FINALIZED",
    "payment_status": "PENDING",
    "amount": {
      "total_amount": {
        "value": 220.20,
        "currency_code": "USD"
      }
    },
    "due_date": "2025-07-28",
    "issued_date": "2025-07-28",
    "invoice_number": "PPC-9E32-202507-012",
    "version_number": "1",
    "invoice_type": "SUBSCRIPTION",
    "customer": {
      "name": "Test Plan Override Customer",
      "external_id": "5eb02857-a71e-4ea2-bcf9-1752555395",
      "email": "finance@techstart.io",
      "id": "5a31b634-3213-42f5-a184-c68f93e47dc1"
    },
    "created_at": "2025-07-28T00:10:01Z",
    "updated_at": "2025-07-28T00:10:01Z"
  }
}

{
  "id": "8PT597110X687430LKGECATA",
  "create_time": "2025-05-27T19:26:01Z",
  "event_version": "1.0",
  "summary": "Invoice payment is overdue",
  "resource_version": "1.0",
  "links": [
    {
      "href": "https://api-m.paypal.com/v1/notifications/webhooks-events/8PT597110X687430LKGECATA",
      "rel": "self",
      "method": "GET"
    }
  ],
  "resource_type": "invoice",
  "event_type": "USAGE-BILLING.INVOICE.PAYMENT.OVERDUE",
  "resource": {
    "id": "27986ceb-bb27-461d-82b1-f044646e192d",
    "sequential_id": 5,
    "status": "FINALIZED",
    "payment_status": "PENDING",
    "amount": {
      "total_amount": {
        "value": 220.20,
        "currency_code": "USD"
      }
    },
    "due_date": "2025-07-14",
    "issued_date": "2025-07-01",
    "invoice_number": "PPC-9E32-202507-012",
    "version_number": "1",
    "payment_overdue": true,
    "invoice_type": "SUBSCRIPTION",
    "customer": {
      "name": "Test Plan Override Customer",
      "external_id": "5eb02857-a71e-4ea2-bcf9-1752555395",
      "email": "finance@techstart.io",
      "id": "5a31b634-3213-42f5-a184-c68f93e47dc1"
    },
    "created_at": "2025-07-01T00:10:01Z",
    "updated_at": "2025-07-15T00:00:00Z"
  }
}

{
  "id": "8PT597110X687430LKGECATA",
  "create_time": "2025-05-27T19:26:01Z",
  "event_version": "1.0",
  "summary": "Invoice payment succeeded",
  "resource_version": "1.0",
  "links": [
    {
      "href": "https://api-m.paypal.com/v1/notifications/webhooks-events/8PT597110X687430LKGECATA",
      "rel": "self",
      "method": "GET"
    }
  ],
  "resource_type": "invoice",
  "event_type": "USAGE-BILLING.INVOICE.PAYMENT.SUCCEEDED",
  "resource": {
    "id": "27986ceb-bb27-461d-82b1-f044646e192d",
    "sequential_id": 5,
    "status": "FINALIZED",
    "payment_status": "SUCCEEDED",
    "amount": {
      "total_amount": {
        "value": 220.20,
        "currency_code": "USD"
      }
    },
    "due_date": "2025-07-28",
    "issued_date": "2025-07-28",
    "invoice_number": "PPC-9E32-202507-012",
    "version_number": "3",
    "payment_overdue": false,
    "invoice_type": "SUBSCRIPTION",
    "customer": {
      "name": "Test Plan Override Customer",
      "external_id": "5eb02857-a71e-4ea2-bcf9-1752555395",
      "email": "finance@techstart.io",
      "id": "5a31b634-3213-42f5-a184-c68f93e47dc1"
    },
    "created_at": "2025-07-28T00:10:01Z",
    "updated_at": "2025-07-28T14:30:00Z"
  }
}

{
  "id": "8PT597110X687430LKGECATA",
  "create_time": "2025-05-27T19:26:01Z",
  "event_version": "1.0",
  "summary": "Invoice payment failed",
  "resource_version": "1.0",
  "links": [
    {
      "href": "https://api-m.paypal.com/v1/notifications/webhooks-events/8PT597110X687430LKGECATA",
      "rel": "self",
      "method": "GET"
    }
  ],
  "resource_type": "invoice",
  "event_type": "USAGE-BILLING.INVOICE.PAYMENT.FAILED",
  "resource": {
    "id": "27986ceb-bb27-461d-82b1-f044646e192d",
    "sequential_id": 5,
    "status": "FINALIZED",
    "payment_status": "FAILED",
    "amount": {
      "total_amount": {
        "value": 220.20,
        "currency_code": "USD"
      }
    },
    "due_date": "2025-07-28",
    "issued_date": "2025-07-28",
    "invoice_number": "PPC-9E32-202507-012",
    "version_number": "2",
    "payment_overdue": true,
    "invoice_type": "SUBSCRIPTION",
    "customer": {
      "name": "Test Plan Override Customer",
      "external_id": "5eb02857-a71e-4ea2-bcf9-1752555395",
      "email": "finance@techstart.io",
      "id": "5a31b634-3213-42f5-a184-c68f93e47dc1"
    },
    "created_at": "2025-07-28T00:10:01Z",
    "updated_at": "2025-07-28T12:30:00Z"
  }
}

{
  "id": "8PT597110X687430LKGECATA",
  "create_time": "2025-05-27T19:26:01Z",
  "event_version": "1.0",
  "summary": "A credit note was created",
  "resource_version": "1.0",
  "links": [
    {
      "href": "https://api-m.paypal.com/v1/notifications/webhooks-events/8PT597110X687430LKGECATA",
      "rel": "self",
      "method": "GET"
    }
  ],
  "resource_type": "credit-note",
  "event_type": "USAGE-BILLING.CREDIT-NOTE.CREATED",
  "resource": {
    "id": "cn_01H2XT1G7N8E2JHJKBVPDS0TQD",
    "billing_entity_code": "acme_inc",
    "sequential_id": 3,
    "number": "CN-2025-0001",
    "invoice_id": "27986ceb-bb27-461d-82b1-f044646e192d",
    "invoice_number": "PPC-9E32-202507-012",
    "issuing_date": "2025-05-27",
    "credit_status": "AVAILABLE",
    "refund_status": "PENDING",
    "reason": "ORDER_CANCELLATION",
    "description": "Service credit for downtime",
    "total_amount": {
      "value": 50.00,
      "currency_code": "USD"
    },
    "credit_amount": {
      "value": 50.00,
      "currency_code": "USD"
    },
    "refund_amount": {
      "value": 0.00,
      "currency_code": "USD"
    },
    "balance_amount": {
      "value": 50.00,
      "currency_code": "USD"
    },
    "taxes_amount": {
      "value": 0.00,
      "currency_code": "USD"
    },
    "taxes_rate": 0.00,
    "sub_total_excluding_taxes_amount": {
      "value": 50.00,
      "currency_code": "USD"
    },
    "created_at": "2025-05-27T19:25:00Z",
    "updated_at": "2025-05-27T19:25:00Z"
  }
}

{
  "id": "8PT597110X687430LKGECATA",
  "create_time": "2025-05-27T19:26:01Z",
  "event_version": "1.0",
  "summary": "Credit note refund failed",
  "resource_version": "1.0",
  "links": [
    {
      "href": "https://api-m.paypal.com/v1/notifications/webhooks-events/8PT597110X687430LKGECATA",
      "rel": "self",
      "method": "GET"
    }
  ],
  "resource_type": "credit-note",
  "event_type": "USAGE-BILLING.CREDIT-NOTE.REFUND.FAILED",
  "resource": {
    "id": "cn_01H2XT1G7N8E2JHJKBVPDS0TQD",
    "billing_entity_code": "acme_inc",
    "sequential_id": 3,
    "number": "CN-2025-0001",
    "invoice_id": "27986ceb-bb27-461d-82b1-f044646e192d",
    "invoice_number": "PPC-9E32-202507-012",
    "issuing_date": "2025-05-27",
    "credit_status": "AVAILABLE",
    "refund_status": "FAILED",
    "reason": "ORDER_CANCELLATION",
    "description": "Service credit for downtime",
    "total_amount": {
      "value": 50.00,
      "currency_code": "USD"
    },
    "credit_amount": {
      "value": 0.00,
      "currency_code": "USD"
    },
    "refund_amount": {
      "value": 50.00,
      "currency_code": "USD"
    },
    "balance_amount": {
      "value": 0.00,
      "currency_code": "USD"
    },
    "taxes_amount": {
      "value": 0.00,
      "currency_code": "USD"
    },
    "taxes_rate": 0.00,
    "sub_total_excluding_taxes_amount": {
      "value": 50.00,
      "currency_code": "USD"
    },
    "created_at": "2025-05-27T19:25:00Z",
    "updated_at": "2025-05-27T20:30:00Z"
  }
}

{
  "id": "8PT597110X687430LKGECATA",
  "create_time": "2025-05-27T19:26:01Z",
  "event_version": "1.0",
  "summary": "A subscription was updated",
  "resource_version": "1.0",
  "links": [
    {
      "href": "https://api-m.paypal.com/v1/notifications/webhooks-events/8PT597110X687430LKGECATA",
      "rel": "self",
      "method": "GET"
    }
  ],
  "resource_type": "subscription",
  "event_type": "USAGE-BILLING.SUBSCRIPTION.UPDATED",
  "resource": {
    "id": "d9e9d0c0-d672-4299-8b8e-9d20ca20f465",
    "external_customer_id": "5eb02857-a71e-4ea2-bcf9-1752555395",
    "external_id": "SUB_1752779018503",
    "plan_code": "ubb_plan_1753826420",
    "billing_time": "CALENDAR",
    "status": "ACTIVE",
    "start_date": "2025-06-27T20:44:21Z",
    "current_period_start": "2025-07-01T00:00:00Z",
    "current_period_end": "2025-07-31T23:59:59Z",
    "plan_overrides": {
      "amount": {
        "value": 50,
        "currency_code": "USD"
      },
      "name": "Updated Pro Plan",
      "trial_period": 7
    }
  }
}

{
  "id": "8PT597110X687430LKGECATA",
  "create_time": "2025-05-27T19:26:01Z",
  "event_version": "1.0",
  "summary": "Subscription was terminated",
  "resource_version": "1.0",
  "links": [
    {
      "href": "https://api-m.paypal.com/v1/notifications/webhooks-events/8PT597110X687430LKGECATA",
      "rel": "self",
      "method": "GET"
    }
  ],
  "resource_type": "subscription",
  "event_type": "USAGE-BILLING.SUBSCRIPTION.TERMINATED",
  "resource": {
    "id": "d9e9d0c0-d672-4299-8b8e-9d20ca20f465",
    "external_customer_id": "5eb02857-a71e-4ea2-bcf9-1752555395",
    "external_id": "SUB_1752779018503",
    "plan_code": "ubb_plan_1753826420",
    "billing_time": "ANNIVERSARY",
    "status": "TERMINATED",
    "start_date": "2025-03-01T00:00:00Z",
    "terminated_at": "2025-05-27T19:26:01Z",
    "current_period_start": "2025-05-01T00:00:00Z",
    "current_period_end": "2025-05-27T19:26:01Z"
  }
}

{
  "id": "8PT597110X687430LKGECATA",
  "create_time": "2025-05-27T19:26:01Z",
  "event_version": "1.0",
  "summary": "Subscription trial period ended",
  "resource_version": "1.0",
  "links": [
    {
      "href": "https://api-m.paypal.com/v1/notifications/webhooks-events/8PT597110X687430LKGECATA",
      "rel": "self",
      "method": "GET"
    }
  ],
  "resource_type": "subscription",
  "event_type": "USAGE-BILLING.SUBSCRIPTION.TRIAL.ENDED",
  "resource": {
    "id": "d9e9d0c0-d672-4299-8b8e-9d20ca20f465",
    "external_customer_id": "5eb02857-a71e-4ea2-bcf9-1752555395",
    "external_id": "SUB_1752779018503",
    "plan_code": "ubb_plan_1753826420",
    "billing_time": "ANNIVERSARY",
    "status": "ACTIVE",
    "start_date": "2025-05-13T19:26:01Z",
    "current_period_start": "2025-05-27T19:26:01Z",
    "current_period_end": "2025-06-27T19:26:01Z",
    "trial_ended_at": "2025-05-27T19:26:01Z"
  }
}

​Subscription alerts

​Wallet events

​Wallet transaction events

​Invoice events

​Credit note events

​Subscription lifecycle events

​Handle webhook events

​Sample webhook payloads

Subscription alerts

Wallet events

Wallet transaction events

Invoice events

Credit note events

Subscription lifecycle events

Handle webhook events

Sample webhook payloads