# Subscriptions Webhooks

## Overview

Ryft provides several webhook events related to **subscriptions** that allow you to stay informed about the status and lifecycle of subscriptions in your account. These webhooks can be used to automate workflows, update your database, or trigger other actions in your system.

We highly recommend using these webhooks, to ensure you can correctly handle different scenarios that may arise with subscriptions, such as renewals, cancellations, and payment failures.

## Subscription Events

These events are related to the lifecycle of a subscription, including its creation, updates, cancellations, and renewals.

Subscription.created
This event is triggered when a subscription is created in your Ryft account. Note that the `status` of the subscription can be any of the following: `Pending`, `Active`, `PastDue`, depending on how the subscription was created.


```json Subscription.created - Payload Example
{
    "id": "ev_XXXXXXXX",
    "eventType": "Subscription.created",
    "data": {
        "id": "sub_XXXXXXXX",
        "status": "PastDue",
        "customer": {"id": "cus_XXXXXXXX"},
        "paymentSessions": {
            "initial": {
                "id": "ps_XXXXXXXX",
                "clientSecret": "ps_XXXXXXXX_secret_XXXXXXXX",
            },
            "latest": {
                "id": "ps_XXXXXXXX",
                "clientSecret": "ps_XXXXXXXX_secret_XXXXXXXX",
            },
        },
        "price": {
            "amount": 100,
            "currency": "GBP",
            "interval": {"unit": "Days", "count": 1, "times": 7},
        },
        "balance": {"amount": 100},
        "billingDetail": {
            "totalCycles": 7,
            "currentCycle": 1,
            "currentCycleStartTimestamp": 1758844800,
            "currentCycleEndTimestamp": 1758931199,
            "billingCycleTimestamp": 1758844800,
            "nextBillingTimestamp": 1758952800,
            "failureDetail": {"paymentAttempts": 1},
        },
        "paymentSettings": {
            "statementDescriptor": {"descriptor": "Test Descriptor", "city": "London"}
        },
        "createdTimestamp": 1758897312,
        "amount": 100,
        "currency": "GBP",
    },
    "createdTimestamp": 1758897313,
    "lastUpdatedTimestamp": 1758897313,
    "deliveryStatus": "None",
}
```

Subscription.updated
This event is triggered when a subscription is updated in your Ryft account. This can include changes to the plan, billing cycle, or other subscription details.


```json Subscription.updated - Payload Example
{
    "id": "ev_XXXXXXXX",
    "eventType": "Subscription.updated",
    "data": {
        "id": "sub_XXXXXXXX",
        "status": "Active",
        "customer": {"id": "cus_XXXXXXXX"},
        "paymentMethod": {
            "id": "pmt_XXXXXXXX",
            "tokenizedDetails": {
                "id": "pmt_XXXXXXXX",
                "stored": true,
            },
        },
        "paymentSessions": {
            "initial": {"id": "ps_XXXXXXXX"},
            "latest": {"id": "ps_XXXXXXXX"},
        },
        "price": {
            "amount": 100,
            "currency": "GBP",
            "interval": {"unit": "Days", "count": 1, "times": 7},
        },
        "balance": {"amount": 0},
        "billingDetail": {
            "totalCycles": 7,
            "currentCycle": 6,
            "currentCycleStartTimestamp": 1759276800,
            "currentCycleEndTimestamp": 1759363199,
            "billingCycleTimestamp": 1758844800,
            "nextBillingTimestamp": 1759384800,
        },
        "paymentSettings": {
            "statementDescriptor": {"descriptor": "Test Descriptor", "city": "London"}
        },
        "createdTimestamp": 1758897312,
        "amount": 100,
        "currency": "GBP",
    },
    "createdTimestamp": 1759276818,
    "lastUpdatedTimestamp": 1759276818,
    "deliveryStatus": "None",
}
```

Subscription.paused
This event is triggered when a subscription is paused. Note that this happens asynchronously.


```json Subscription.paused - Payload Example
{
    "id": "ev_XXXXXXXX",
    "eventType": "Subscription.paused",
    "data": {
        "id": "sub_XXXXXXXX",
        "status": "Paused",
        "description": "Change price",
        "customer": {"id": "cus_XXXXXXXX"},
        "paymentMethod": {
            "id": "pmt_XXXXXXXX",
            "tokenizedDetails": {
                "id": "pmt_XXXXXXXX",
                "stored": true,
            },
        },
        "paymentSessions": {
            "initial": {"id": "ps_XXXXXXXX"},
            "latest": {"id": "ps_XXXXXXXX"},
        },
        "price": {
            "amount": 200,
            "currency": "GBP",
            "interval": {"unit": "Days", "count": 1, "times": 7},
        },
        "balance": {"amount": 0},
        "pausePaymentDetail": {"pausedAtTimestamp": 1758931200},
        "billingDetail": {
            "totalCycles": 7,
            "currentCycle": 2,
            "currentCycleStartTimestamp": 1758844800,
            "currentCycleEndTimestamp": 1758931199,
            "billingCycleTimestamp": 1758758400,
        },
        "paymentSettings": {
            "statementDescriptor": {"descriptor": "Test Descriptor", "city": "London"}
        },
        "createdTimestamp": 1758808389,
        "amount": 200,
        "currency": "GBP",
    },
    "createdTimestamp": 1758931231,
    "lastUpdatedTimestamp": 1758931231,
    "deliveryStatus": "None",
}
```

Subscription.resumed
This event is triggered when a subscription is resumed from a paused state. Note that this can also happen for subscriptions that were paused until a future date.


```json Subscription.resumed - Payload Example
{
    "id": "ev_XXXXXXXX",
    "eventType": "Subscription.resumed",
    "data": {
        "id": "sub_XXXXXXXX",
        "amount": 500,
        "currency": "GBP",
        "status": "Active",
        "metadata": {
            "customerId": "ef8995ce-ed5c-4f77-b04e-df86de5c11b8",
            "tarrif": "123",
        },
        "customer": {"id": "cus_XXXXXXXX"},
        "paymentMethod": {"id": "pmt_XXXXXXXX"},
        "createdTimestamp": 1659538083,
    },
    "createdTimestamp": 1659538083,
}
```

Subscription.cancelled
This event is triggered when a subscription is cancelled in your Ryft account. This indicates that the subscription will not renew at the end of the current billing cycle.


```json Subscription.cancelled - Payload Example
{
    "id": "ev_XXXXXXXX",
    "eventType": "Subscription.cancelled",
    "data": {
        "id": "sub_XXXXXXXX",
        "status": "Cancelled",
        "customer": {"id": "cus_XXXXXXXX"},
        "price": {
            "amount": 2625,
            "currency": "GBP",
            "interval": {"unit": "Months", "count": 1, "times": 7},
        },
        "balance": {"amount": 0},
        "cancelDetail": {"cancelledAtTimestamp": 1759482911},
        "billingDetail": {
            "totalCycles": 7,
            "currentCycle": 1,
            "currentCycleStartTimestamp": 1761264000,
            "currentCycleEndTimestamp": 1763942399,
            "billingCycleTimestamp": 1761297603,
        },
        "metadata": {
            "customerId": "156",
            "basketId": "11016",
            "customerEmail": "test@gmail.com",
        },
        "paymentSettings": {
            "statementDescriptor": {"descriptor": "Test Descriptor", "city": "London"}
        },
        "createdTimestamp": 1758799387,
        "amount": 2625,
        "currency": "GBP",
    },
    "createdTimestamp": 1759482912,
    "lastUpdatedTimestamp": 1759482912,
    "deliveryStatus": "None",
}
```

Subscription.ended
This event is triggered when a subscription is in its final billing cycle and has reached its end date.


```json Subscription.ended - Payload Example
{
    "id": "ev_XXXXXXXX",
    "eventType": "Subscription.ended",
    "data": {
        "id": "sub_XXXXXXXX",
        "status": "Ended",
        "customer": {"id": "cus_XXXXXXXX"},
        "paymentMethod": {
            "id": "pmt_XXXXXXXX",
            "tokenizedDetails": {
                "id": "pmt_XXXXXXXX",
                "stored": true,
            },
        },
        "paymentSessions": {
            "initial": {"id": "ps_XXXXXXXX"},
            "latest": {"id": "ps_XXXXXXXX"},
        },
        "price": {
            "amount": 100,
            "currency": "GBP",
            "interval": {"unit": "Days", "count": 1, "times": 7},
        },
        "balance": {"amount": 0},
        "billingDetail": {
            "totalCycles": 7,
            "currentCycle": 7,
            "currentCycleStartTimestamp": 1759363200,
            "currentCycleEndTimestamp": 1759449599,
            "billingCycleTimestamp": 1758844800,
        },
        "paymentSettings": {
            "statementDescriptor": {"descriptor": "Test Descriptor", "city": "London"}
        },
        "createdTimestamp": 1758897312,
        "amount": 100,
        "currency": "GBP",
    },
    "createdTimestamp": 1759384867,
    "lastUpdatedTimestamp": 1759384867,
    "deliveryStatus": "None",
}
```