PApaddlehq
Subscriptions

subscription.canceled

Occurs when a subscription is canceled. Its status field changes to canceled.

If you choose to cancel a subscription immediately, the subscription status changes to canceled and subscription.canceled occurs.

If you choose to cancel a subscription on the next billing period, Paddle creates a scheduled change to say the subscription should be canceled on the next billing date. subscription.updated occurs at this point. On the next billing date, the subscription status changes to canceled and subscription.canceled occurs.

Payload includes the complete subscription entity, except management_urls. Subscription management links are temporary, so they're not included. Get a subscription using the API to get management links for a subscription.

postWebhooksubscription.canceled

Headers

paddle_signaturestring required

Signature for this request. Use to verify that webhooks come from Paddle.

Payload

event_idstring required

Unique Paddle ID for this event, prefixed with evt_.

event_type'address.created' | 'address.imported' | 'address.updated' | 'adjustment.created' | 'adjustment.updated' | 'api_key.created' | 'api_key.expired' | 'api_key.expiring' | 'api_key.revoked' | 'api_key.updated' | 'api_key_exposure.created' | 'business.created' | 'business.imported' | 'business.updated' | 'client_token.created' | 'client_token.revoked' | 'client_token.updated' | 'customer.created' | 'customer.imported' | 'customer.updated' | 'discount.created' | 'discount.imported' | 'discount.updated' | 'discount_group.created' | 'discount_group.updated' | 'payment_method.saved' | 'payment_method.deleted' | 'payout.created' | 'payout.paid' | 'price.created' | 'price.imported' | 'price.updated' | 'product.created' | 'product.imported' | 'product.updated' | 'report.created' | 'report.updated' | 'subscription.activated' | 'subscription.canceled' | 'subscription.created' | 'subscription.imported' | 'subscription.past_due' | 'subscription.paused' | 'subscription.resumed' | 'subscription.trialing' | 'subscription.updated' | 'transaction.billed' | 'transaction.canceled' | 'transaction.completed' | 'transaction.created' | 'transaction.paid' | 'transaction.past_due' | 'transaction.payment_failed' | 'transaction.ready' | 'transaction.revised' | 'transaction.updated' required

Type of event sent by Paddle, in the format entity.event_type.

occurred_atstring date-time required

RFC 3339 datetime string of when this event occurred.

notification_idstring required

Unique Paddle ID for this notification, prefixed with ntf_.

Example payload

{
  "event_id": "evt_01gks14ge726w50ch2tmaw2a1x",
  "occurred_at": "2024-10-12T07:20:50.52Z",
  "notification_id": "ntf_01ghbkd0frb9k95cnhwd1bxpvk",
  "data": {
    "id": "sub_01h04vsc0qhwtsbsxh3422wjs4",
    "customer_id": "ctm_01grnn4zta5a1mf02jjze7y2ys",
    "address_id": "add_01gm302t81w94gyjpjpqypkzkf",
    "business_id": "biz_01grrebrzaee2qj2fqqhmcyzaj",
    "created_at": "2024-10-12T07:20:50.52Z",
    "updated_at": "2024-10-12T07:20:50.52Z",
    "started_at": "2024-10-12T07:20:50.52Z",
    "first_billed_at": "2024-10-12T07:20:50.52Z",
    "next_billed_at": "2024-10-12T07:20:50.52Z",
    "paused_at": "2024-10-12T07:20:50.52Z",
    "canceled_at": "2024-10-12T07:20:50.52Z",
    "discount": {
      "id": "dsc_01gv5kpg05xp104ek2fmgjwttf",
      "starts_at": "2024-10-12T07:20:50.52Z",
      "ends_at": "2024-10-12T07:20:50.52Z"
    },
    "current_billing_period": {
      "starts_at": "2024-10-12T07:20:50.52Z",
      "ends_at": "2024-10-12T07:20:50.52Z"
    },
    "scheduled_change": {
      "effective_at": "2024-10-12T07:20:50.52Z",
      "resume_at": "2024-10-12T07:20:50.52Z"
    },
    "items": [
      {
        "created_at": "2024-10-12T07:20:50.52Z",
        "updated_at": "2024-10-13T07:20:50.52Z",
        "previously_billed_at": "2024-10-12T07:20:50.52Z",
        "next_billed_at": "2024-10-12T07:20:50.52Z",
        "trial_dates": {
          "starts_at": "2024-10-12T07:20:50.52Z",
          "ends_at": "2024-10-12T07:20:50.52Z"
        },
        "price": {
          "id": "pri_01gsz8z1q1n00f12qt82y31smh",
          "product_id": "pro_01gsz97mq9pa4fkyy0wqenepkz",
          "quantity": {
            "minimum": 1,
            "maximum": 100
          },
          "custom_data": {
            "customer_reference_id": "abcd1234"
          },
          "import_meta": {
            "external_id": "9b95b0b8-e10f-441a-862e-1936a6d818ab",
            "imported_from": "paddle_classic"
          },
          "created_at": "2024-10-12T07:20:50.52Z",
          "updated_at": "2024-10-13T07:20:50.52Z"
        },
        "product": {
          "id": "pro_01gsz97mq9pa4fkyy0wqenepkz",
          "custom_data": {
            "customer_reference_id": "abcd1234"
          },
          "import_meta": {
            "external_id": "9b95b0b8-e10f-441a-862e-1936a6d818ab",
            "imported_from": "paddle_classic"
          },
          "created_at": "2024-10-12T07:20:50.52Z",
          "updated_at": "2024-10-13T07:20:50.52Z"
        }
      }
    ],
    "consent_requirements": [
      {
        "id": "subconreq_01gm302t81w94gyjpjpqypkzkf",
        "created_at": "2024-10-12T07:20:50.52Z",
        "consent_period": {
          "starts_at": "2024-10-12T07:20:50.52Z",
          "ends_at": "2024-10-12T07:20:50.52Z"
        },
        "granted_at": "2024-10-12T07:20:50.52Z",
        "voided_at": "2024-10-12T07:20:50.52Z"
      }
    ],
    "custom_data": {
      "customer_reference_id": "abcd1234"
    },
    "import_meta": {
      "external_id": "9b95b0b8-e10f-441a-862e-1936a6d818ab",
      "imported_from": "paddle_classic"
    }
  }
}

Response

Respond with an HTTP 200 status code within 5 seconds to let Paddle know that you successfully received the message.

If your server sends another kind of status code or doesn't respond, Paddle automatically retries using an exponential backoff schedule.

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.