> ## Documentation Index
> Fetch the complete documentation index at: https://razorpay-60c89f9a-mintlify-audit-missing-sections-1778528421.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Subscriptions Webhook Events

> A **Subscription** is an automated recurring payment system that charges customers based on a predefined billing cycle without manual intervention.

## List of Subscriptions Webhook Events

The table below lists the webhook events available for Subscriptions.

## Webhook Event | Description

## `subscription.authenticated`| Sent when the first payment is made on the subscription. This can either be the authorisation amount, the upfront amount, the plan amount or a combination of the plan amount and the upfront amount.

## `subscription.activated` | Sent when the subscription moves to the `active` state either from the `authenticated`, `pending` or `halted` state. If a Subscription moves to the `active` state from the `pending` or `halted` state, only the subsequent invoices that are generated are charged. Existing invoices that were already generated are not charged.

## `subscription.charged` | Sent every time a successful charge is made on the subscription.

## `subscription.completed`| Sent when all the invoices are generated for a subscription and the subscription moves to the `completed` state.

## `subscription.updated` | Sent when a subscription is successfully updated. There is no state change when a subscription is updated.

## `subscription.pending` | Sent when the subscription moves to the `pending` state. This happens when a charge on the card fails. We try to charge the card on a periodic basis while it is in the `pending` state. If the payment fails again, the Webhook is triggered again.

## `subscription.halted`| Sent when all retries have been exhausted and the subscription moves from the `pending` state to the `halted` state. The customer has to manually retry the charge or change the card linked to the subscription, for the subscription to move back to the `active` state.

## `subscription.cancelled` | Sent when a subscription is cancelled and moved to the `cancelled` state.

## `subscription.paused`| Sent when a subscription is paused and moved to the `paused` state.

`subscription.resumed`| Sent when a subscription is resumed and moved to the `resumed` state.

<Info>
  **Handy Tips**
</Info>

The payload for all these events contain the subscription entity. They also contain a payment entity if a payment attempt was made before the event was triggered.

## Sample Payloads

Given below are the sample payloads for Subscription webhook events.

### Subscription Authenticated

```json: subscription.authenticated theme={null}
{
  "entity": "event",
  "account_id": "acc_F5Motm2sJ5Fomd",
  "event": "subscription.authenticated",
  "contains": [
    "subscription"
  ],
  "payload": {
    "subscription": {
      "entity": {
        "id": "sub_F5aa7VaVXtXh80",
        "entity": "subscription",
        "plan_id": "plan_F5Zu0nrXVhHV2m",
        "customer_id": "cust_F5ZuzTm0cqYpzp",
        "status": "authenticated",
        "current_start": null,
        "current_end": null,
        "ended_at": null,
        "quantity": 1,
        "notes": [],
        "charge_at": 1593109800,
        "start_at": 1593109800,
        "end_at": 1598380200,
        "auth_attempts": 0,
        "total_count": 3,
        "paid_count": 0,
        "customer_notify": true,
        "created_at": 1592811228,
        "expire_by": null,
        "short_url": null,
        "has_scheduled_changes": false,
        "change_scheduled_at": null,
        "source": "api",
        "offer_id":"offer_JHD834hjbxzhd38d",
        "remaining_count": 3
      }
    }
  },
  "created_at": 1592811255
}
```

### Subscription Activated

````json: Future start date and no upfront amount theme={null}
{
  "entity": "event",
  "account_id": "acc_BFQ7uQEaa7j2z7",
  "event": "subscription.activated",
  "contains": [
    "subscription"
  ],
  "payload": {
    "subscription": {
      "entity": {
        "id": "sub_DEX6xcJ1HSW4CR",
        "entity": "subscription",
        "plan_id": "plan_BvrFKjSxauOH7N",
        "customer_id": "cust_C0WlbKhp3aLA7W",
        "status": "active",
        "current_start": 1570213800,
        "current_end": 1572892200,
        "ended_at": null,
        "quantity": 1,
        "notes": {
          "notes_key_1": "Tea, Earl Grey, Hot",
          "notes_key_2": "Tea, Earl Grey… decaf."
        },
        "charge_at": 1570213800,
        "start_at": 1570213800,
        "end_at": 1599244200,
        "auth_attempts": 0,
        "total_count": 12,
        "paid_count": 0,
        "customer_notify": true,
        "created_at": 1567689895,
        "expire_by": 1567881000,
        "short_url": null,
        "has_scheduled_changes": false,
        "change_scheduled_at": null,
        "source": "api",
        "offer_id":"offer_JHD834hjbxzhd38d",
        "remaining_count": 11
      }
    }
  },
  "created_at": 1567690383
}
```json: Immediate start date/Upfront amount/Both
{
  "entity": "event",
  "account_id": "acc_BFQ7uQEaa7j2z7",
  "event": "subscription.activated",
  "contains": [
    "subscription"
  ],
  "payload": {
    "subscription": {
      "entity": {
        "id": "sub_DEX6xcJ1HSW4CR",
        "entity": "subscription",
        "plan_id": "plan_BvrFKjSxauOH7N",
        "customer_id": "cust_C0WlbKhp3aLA7W",
        "status": "active",
        "type": 2,
        "current_start": 1570213800,
        "current_end": 1572892200,
        "ended_at": null,
        "quantity": 1,
        "notes": {
          "notes_key_1": "Tea, Earl Grey, Hot",
          "notes_key_2": "Tea, Earl Grey… decaf."
        },
        "charge_at": 1570213800,
        "start_at": 1570213800,
        "end_at": 1599244200,
        "auth_attempts": 0,
        "total_count": 12,
        "paid_count": 1,
        "customer_notify": true,
        "created_at": 1567689895,
        "expire_by": 1567881000,
        "short_url": null,
        "has_scheduled_changes": false,
        "change_scheduled_at": null,
        "source": "api",
        "offer_id":"offer_JHD834hjbxzhd38d",
        "remaining_count": 11
      }
    },
    "payment": {
      "entity": {
        "id": "pay_DEXFWroJ6LikKT",
        "entity": "payment",
        "amount": 100000,
        "currency": "INR",
        "status": "captured",
        "order_id": "order_DEXFWXwO24pDxH",
        "invoice_id": "inv_DEXFWVuM6rPqlK",
        "international": false,
        "method": "card",
        "amount_refunded": 0,
        "amount_transferred": 0,
        "refund_status": null,
        "captured": "1",
        "description": "Recurring Payment via Subscription",
        "card_id": "card_DEXFX0KGtXexrH",
        "card": {
          "id": "card_DEXFX0KGtXexrH",
          "entity": "card",
          "name": "Gaurav Kumar",
          "last4": "5558",
          "network": "MasterCard",
          "type": "credit",
          "issuer": "KARB",
          "international": false,
          "emi": false,
          "expiry_month": 2,
          "expiry_year": 2022
        },
        "bank": null,
        "wallet": null,
        "vpa": null,
        "email": "gaurav.kumar@example.com",
        "contact": "+919876543210",
        "customer_id": "cust_C0WlbKhp3aLA7W",
        "token_id": null,
        "notes": [],
        "fee": 2900,
        "tax": 0,
        "error_code": null,
        "error_description": null,
        "created_at": 1567690382
      }
    },
    "created_at": 1567690383
  }
}
````

### Subscription Charged

```json: subscription.charged theme={null}
{
  "entity": "event",
  "account_id": "acc_BFQ7uQEaa7j2z7",
  "event": "subscription.charged",
  "contains": [
    "subscription",
    "payment"
  ],
  "payload": {
    "subscription": {
      "entity": {
        "id": "sub_DEX6xcJ1HSW4CR",
        "entity": "subscription",
        "plan_id": "plan_BvrFKjSxauOH7N",
        "customer_id": "cust_C0WlbKhp3aLA7W",
        "status": "active",
        "type": 2,
        "current_start": 1570213800,
        "current_end": 1572892200,
        "ended_at": null,
        "quantity": 1,
        "notes": {
          "Important": "Notes for Internal Reference"
        },
        "charge_at": 1572892200,
        "start_at": 1570213800,
        "end_at": 1599244200,
        "auth_attempts": 0,
        "total_count": 12,
        "paid_count": 1,
        "customer_notify": true,
        "created_at": 1567689895,
        "expire_by": 1567881000,
        "short_url": null,
        "has_scheduled_changes": false,
        "change_scheduled_at": null,
        "source": "api",
        "offer_id":"offer_JHD834hjbxzhd38d",
        "remaining_count": 11
      }
    },
    "payment": {
      "entity": {
        "id": "pay_DEXFWroJ6LikKT",
        "entity": "payment",
        "amount": 100000,
        "currency": "INR",
        "status": "captured",
        "order_id": "order_DEXFWXwO24pDxH",
        "invoice_id": "inv_DEXFWVuM6rPqlK",
        "international": false,
        "method": "card",
        "amount_refunded": 0,
        "amount_transferred": 0,
        "refund_status": null,
        "captured": "1",
        "description": "Recurring Payment via Subscription",
        "card_id": "card_DEXFX0KGtXexrH",
        "card": {
          "id": "card_DEXFX0KGtXexrH",
          "entity": "card",
          "name": "Gaurav Kumar",
          "last4": "5558",
          "network": "MasterCard",
          "type": "credit",
          "issuer": "KARB",
          "international": false,
          "emi": false,
          "expiry_month": 2,
          "expiry_year": 2022
        },
        "bank": null,
        "wallet": null,
        "vpa": null,
        "email": "gaurav.kumar@example.com",
        "contact": "+919876543210",
        "customer_id": "cust_C0WlbKhp3aLA7W",
        "token_id": null,
        "notes": [],
        "fee": 2900,
        "tax": 0,
        "error_code": null,
        "error_description": null,
        "created_at": 1567690382
      }
    }
  },
  "created_at": 1567690383
}
```

### Subscription Completed

```json: subscription.completed theme={null}
{
  "entity": "event",
  "account_id": "acc_BFQ7uQEaa7j2z7",
  "event": "subscription.completed",
  "contains": [
    "subscription",
    "payment"
  ],
  "payload": {
    "subscription": {
      "entity": {
        "id": "sub_DEX6xcJ1HSW4CR",
        "entity": "subscription",
        "plan_id": "plan_BvrFKjSxauOH7N",
        "customer_id": "cust_C0WlbKhp3aLA7W",
        "status": "completed",
        "type": 2,
        "current_start": 1599244200,
        "current_end": 1601836200,
        "ended_at": 1599244200,
        "quantity": 1,
        "notes": {
          "Important": "Notes for Internal Reference"
        },
        "charge_at": null,
        "start_at": 1570213800,
        "end_at": 1599244200,
        "auth_attempts": 0,
        "total_count": 12,
        "paid_count": 11,
        "customer_notify": true,
        "created_at": 1567689895,
        "expire_by": 1567881000,
        "short_url": null,
        "has_scheduled_changes": false,
        "change_scheduled_at": null,
        "source": "api",
        "offer_id":"offer_JHD834hjbxzhd38d",
        "remaining_count": 0
      }
    },
    "payment": {
      "entity": {
        "id": "pay_DEXkZ54GsNwVk9",
        "entity": "payment",
        "amount": 100000,
        "currency": "INR",
        "status": "captured",
        "order_id": "order_DEXkYoCpua7kn3",
        "invoice_id": "inv_DEXkYmFDy966lT",
        "international": false,
        "method": "card",
        "amount_refunded": 0,
        "amount_transferred": 0,
        "refund_status": null,
        "captured": "1",
        "description": "Recurring Payment via Subscription",
        "card_id": "card_DEXkZBosDfKGEe",
        "card": {
          "id": "card_DEXkZBosDfKGEe",
          "entity": "card",
          "name": "Gaurav Kumar",
          "last4": "0008",
          "network": "MasterCard",
          "type": "unknown",
          "issuer": "",
          "international": false,
          "emi": false,
          "expiry_month": 11,
          "expiry_year": 2031
        },
        "bank": null,
        "wallet": null,
        "vpa": null,
        "email": "gaurav.kumar@example.com",
        "contact": "+919876543210",
        "customer_id": "cust_C0WlbKhp3aLA7W",
        "token_id": null,
        "notes": [],
        "fee": 2900,
        "tax": 0,
        "error_code": null,
        "error_description": null,
        "created_at": 1567692144
      }
    }
  },
  "created_at": 1567692150
}
```

### Subscription Updated

```json: subscription.updated theme={null}
{
  "entity": "event",
  "account_id": "acc_BFQ7uQEaa7j2z7",
  "event": "subscription.updated",
  "contains": [
    "subscription"
  ],
  "payload": {
    "subscription": {
      "entity": {
        "id": "sub_DEXpmJhEIZK4fe",
        "entity": "subscription",
        "plan_id": "plan_BvrHngQ0xLNnNG",
        "customer_id": "cust_C0WlbKhp3aLA7W",
        "status": "active",
        "type": 3,
        "current_start": 1567692455,
        "current_end": 1570213800,
        "ended_at": null,
        "quantity": 4,
        "notes": {
          "Important": "Notes for Internal Reference"
        },
        "charge_at": 1570213800,
        "start_at": 1567692455,
        "end_at": 1599071400,
        "auth_attempts": 0,
        "total_count": 53,
        "paid_count": 1,
        "customer_notify": true,
        "created_at": 1567692440,
        "expire_by": 1567881000,
        "short_url": null,
        "has_scheduled_changes": false,
        "change_scheduled_at": null,
        "source": "api",
        "offer_id":"offer_JHD834hjbxzhd38d",
        "remaining_count": 52
      }
    }
  },
  "created_at": 1567692560
}
```

### Subscription Pending

```json: subscription.pending theme={null}
{
  "entity": "event",
  "account_id": "acc_BFQ7uQEaa7j2z7",
  "event": "subscription.pending",
  "contains": [
    "subscription"
  ],
  "payload": {
    "subscription": {
      "entity": {
        "id": "sub_DEX6xcJ1HSW4CR",
        "entity": "subscription",
        "plan_id": "plan_BvrFKjSxauOH7N",
        "customer_id": "cust_C0WlbKhp3aLA7W",
        "status": "pending",
        "type": 2,
        "current_start": 1572892200,
        "current_end": 1575484200,
        "ended_at": null,
        "quantity": 1,
        "notes": {
          "Important": "Notes for Internal Reference"
        },
        "charge_at": 1572978600,
        "start_at": 1570213800,
        "end_at": 1599244200,
        "auth_attempts": 1,
        "total_count": 12,
        "paid_count": 1,
        "customer_notify": true,
        "created_at": 1567689895,
        "expire_by": 1567881000,
        "short_url": null,
        "has_scheduled_changes": false,
        "change_scheduled_at": null,
        "source": "api",
        "offer_id":"offer_JHD834hjbxzhd38d",
        "remaining_count": 10
      }
    }
  },
  "created_at": 1567691026
}
```

### Subscription Halted

```json: subscription.halted theme={null}
{
  "entity": "event",
  "account_id": "acc_BFQ7uQEaa7j2z7",
  "event": "subscription.halted",
  "contains": [
    "subscription"
  ],
  "payload": {
    "subscription": {
      "entity": {
        "id": "sub_DEX6xcJ1HSW4CR",
        "entity": "subscription",
        "plan_id": "plan_BvrFKjSxauOH7N",
        "customer_id": "cust_C0WlbKhp3aLA7W",
        "status": "halted",
        "type": 2,
        "current_start": 1572892200,
        "current_end": 1575484200,
        "ended_at": null,
        "quantity": 1,
        "notes": {
          "Important": "Notes for Internal Reference"
        },
        "charge_at": 1575484200,
        "start_at": 1570213800,
        "end_at": 1599244200,
        "auth_attempts": 4,
        "total_count": 12,
        "paid_count": 1,
        "customer_notify": true,
        "created_at": 1567689895,
        "expire_by": 1567881000,
        "short_url": null,
        "has_scheduled_changes": false,
        "change_scheduled_at": null,
        "source": "api",
        "offer_id":"offer_JHD834hjbxzhd38d",
        "remaining_count": 10
      }
    }
  },
  "created_at": 1567691269
}
```

### Subscription Paused

```json: subscription.paused theme={null}
{
  "entity": "event",
  "account_id": "acc_Fe3fPCmiStazv3",
  "event": "subscription.paused",
  "contains": [
    "subscription"
  ],
  "payload": {
    "subscription": {
      "entity": {
        "id": "sub_FeQ9WWOjGUZMpG",
        "entity": "subscription",
        "plan_id": "plan_FeMmuaVVa1HR0W",
        "customer_id": "cust_FeOEa4PPa0by07",
        "status": "paused",
        "type": 1,
        "current_start": 1600416437,
        "current_end": 1602959400,
        "ended_at": null,
        "quantity": 1,
        "notes": [],
        "charge_at": null,
        "start_at": 1600416437,
        "end_at": 1610908200,
        "auth_attempts": 0,
        "total_count": 5,
        "paid_count": 1,
        "customer_notify": true,
        "created_at": 1600416405,
        "expire_by": null,
        "short_url": null,
        "has_scheduled_changes": false,
        "change_scheduled_at": null,
        "source": "api",
        "offer_id":"offer_JHD834hjbxzhd38d",
        "payment_method": "card",
        "remaining_count": 4,
        "pause_initiated_by": "self",
        "cancel_initiated_by": null
      }
    }
  },
  "created_at": 1600416473
}
```

### Subscription Resumed

```json: subscription.resumed theme={null}
{
  "entity": "event",
  "account_id": "acc_Fe3fPCmiStazv3",
  "event": "subscription.resumed",
  "contains": [
    "subscription"
  ],
  "payload": {
    "subscription": {
      "entity": {
        "id": "sub_FeQ9WWOjGUZMpG",
        "entity": "subscription",
        "plan_id": "plan_FeMmuaVVa1HR0W",
        "customer_id": "cust_FeOEa4PPa0by07",
        "status": "active",
        "type": 1,
        "current_start": 1600416437,
        "current_end": 1602959400,
        "ended_at": null,
        "quantity": 1,
        "notes": [],
        "charge_at": 1602959400,
        "start_at": 1600416437,
        "end_at": 1610908200,
        "auth_attempts": 0,
        "total_count": 5,
        "paid_count": 1,
        "customer_notify": true,
        "created_at": 1600416405,
        "expire_by": null,
        "short_url": null,
        "has_scheduled_changes": false,
        "change_scheduled_at": null,
        "source": "api",
        "offer_id":"offer_JHD834hjbxzhd38d",
        "payment_method": "card",
        "remaining_count": 4,
        "pause_initiated_by": null,
        "cancel_initiated_by": null
      }
    }
  },
  "created_at": 1600416481
}
```

### Subscription Cancelled

```json: subscription.cancelled theme={null}
{
  "entity": "event",
  "account_id": "acc_BFQ7uQEaa7j2z7",
  "event": "subscription.cancelled",
  "contains": [
    "subscription"
  ],
  "payload": {
    "subscription": {
      "entity": {
        "id": "sub_DEXpmJhEIZK4fe",
        "entity": "subscription",
        "plan_id": "plan_BvrHngQ0xLNnNG",
        "customer_id": "cust_C0WlbKhp3aLA7W",
        "status": "cancelled",
        "type": 3,
        "current_start": 1568226600,
        "current_end": 1568831400,
        "ended_at": 1567692729,
        "quantity": 4,
        "notes": {
          "Important": "Notes for Internal Reference"
        },
        "charge_at": null,
        "start_at": 1567692455,
        "end_at": 1599071400,
        "auth_attempts": 0,
        "total_count": 53,
        "paid_count": 2,
        "customer_notify": true,
        "created_at": 1567692440,
        "expire_by": 1567881000,
        "short_url": null,
        "has_scheduled_changes": false,
        "change_scheduled_at": null,
        "source": "api",
        "offer_id":"offer_JHD834hjbxzhd38d",
        "remaining_count": 51
      }
    }
  },
  "created_at": 1567692732
}
```

<Warning>
  **Watch Out!**

  * If you have changed your webhook secret, remember to use the old secret for webhook signature validation while retrying older requests. Using the new secret will lead to a signature mismatch.

  * While generating a signature at your end, ensure that the webhook body is passed as an argument in the **raw webhook request body**. **Do not parse or cast the webhook request body**.
</Warning>