PApaypal
Subscriptions

Subscription updated.

Webhook for Subscription updated.

postWebhookusage-billing.subscription.updated

Headers

paypal-transmission-idstring

The unique ID of the transmission, from the paypal-transmission-id HTTP header.

paypal-transmission-timestring

The date and time when the message was transmitted, from the paypal-transmission-time HTTP header.

Payload

idstring required

Unique identifier for the webhook event.

create_timestring date-time required

Date and time in ISO 8601 format.

event_versionstring

Version of the event schema.

summarystring

Brief description of the event.

resource_versionstring

Version of the resource schema.

resource_type'subscription-alert' | 'wallet' | 'wallet-transaction' | 'credit-note' | 'invoice' | 'subscription' required

Type of resource that triggered the webhook.

event_type'USAGE-BILLING.SUBSCRIPTION-ALERT.TRIGGERED' | 'USAGE-BILLING.WALLET.CREATED' | 'USAGE-BILLING.WALLET.UPDATED' | 'USAGE-BILLING.WALLET.NET-BALANCE-DEPLETED' | 'USAGE-BILLING.WALLET.TERMINATED' | 'USAGE-BILLING.WALLET-TRANSACTION.CREATED' | 'USAGE-BILLING.WALLET-TRANSACTION.UPDATED' | 'USAGE-BILLING.CREDIT-NOTE.CREATED' | 'USAGE-BILLING.CREDIT-NOTE.REFUND.FAILED' | 'USAGE-BILLING.INVOICE.CREATED' | 'USAGE-BILLING.INVOICE.PAYMENT.OVERDUE' | 'USAGE-BILLING.INVOICE.PAYMENT.SUCCEEDED' | 'USAGE-BILLING.INVOICE.PAYMENT.FAILED' | 'USAGE-BILLING.SUBSCRIPTION.UPDATED' | 'USAGE-BILLING.SUBSCRIPTION.TERMINATED' | 'USAGE-BILLING.SUBSCRIPTION.TRIAL.ENDED' required

Type of event that occurred in webhooks.

Example payload

{
  "id": "8PT597110X687430LKGECATA",
  "create_time": "2023-10-01T12:00:00Z",
  "event_version": "1.0",
  "summary": "A new alert was triggered.",
  "resource_version": "1.0",
  "links": [
    {
      "href": "https://api-m.paypal.com/v1/notfications/webhooks-events/8PT597110X687430LKGECATA",
      "rel": "self",
      "method": "GET"
    }
  ],
  "resource": {
    "name": "Subscription_1",
    "start_date": "2025-06-01T00:00:00Z",
    "end_date": "2028-01-01T00:00:00Z",
    "external_customer_id": "client-jkl101",
    "external_id": "SUB_1752779018503",
    "plan_code": "Plan-Code-1753840215",
    "billing_time": "CALENDAR",
    "id": "b71befc2-4799-402c-9d13-ca1f72759c64",
    "status": "ACTIVE",
    "plan_overrides": {
      "amount": {
        "value": 120.35,
        "currency_code": "USD"
      },
      "description": "Plan for early stage startups",
      "invoice_display_name": "Startup plan",
      "name": "Startup",
      "charges": [
        {
          "id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
          "charge_model": "GRADUATED",
          "taxes": [
            {
              "name": "TVA",
              "rate": "20.00",
              "description": "French standard VAT",
              "code": "standard_vat",
              "id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
              "created_at": "2025-06-01T00:00:00Z"
            }
          ],
          "min_amount": {
            "value": 120.35,
            "currency_code": "USD"
          }
        }
      ],
      "minimum_commitment": {
        "amount": {
          "value": 120.35,
          "currency_code": "USD"
        },
        "invoice_display_name": "Minimum Commitment (C1)",
        "taxes": [
          {
            "name": "TVA",
            "rate": "20.00",
            "description": "French standard VAT",
            "code": "standard_vat",
            "id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
            "created_at": "2025-06-01T00:00:00Z"
          }
        ],
        "id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
        "plan_code": "premium",
        "created_at": "2022-04-29T08:59:51Z",
        "updated_at": "2022-04-29T08:59:51Z"
      },
      "chargeUsage": [
        {
          "id": "545-1a90-1a90-1a90-1a90-1a901a901a90",
          "recurring": "true",
          "threshold_display_name": "Startup",
          "created_at": "2023-10-01T12:00:00Z",
          "updated_at": "2023-10-01T12:00:00Z",
          "amount": {
            "value": 120.35,
            "currency_code": "USD"
          }
        }
      ],
      "taxes": [
        {
          "name": "TVA",
          "rate": "20.00",
          "description": "French standard VAT",
          "code": "standard_vat",
          "id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
          "created_at": "2025-06-01T00:00:00Z"
        }
      ],
      "trial_period": 5
    },
    "canceled_at": "2025-01-01T00:00:00Z",
    "terminated_at": "2025-01-01T00:00:00Z",
    "current_period_start": "2025-05-01T00:00:00Z",
    "current_period_end": "2023-10-01T12:00:00Z",
    "trial_ended_at": "2025-05-01T00:00:00Z"
  }
}

Response

Return a 204 status to indicate that the data was received successfully.

Changes

Webhooks have no change history: a webhook is keyed by its event name rather than a path and method, so no recorded change can name it.