> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.coinflow.cash/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.coinflow.cash/_mcp/server.

# Subscription Webhooks

> **Note**
>
> ## Webhooks may be sent more than once—add deduplication logic to prevent duplicate events.

The webhook examples on this page assume bank or card settlement. The `signature` field and any non-zero `gasFees` only appear on advanced stablecoin settlement paths.

## ✅ Event Types

Subscription webhooks fall into two categories:

* **`Subscription` category** — lifecycle events unique to subscriptions (created, canceled, expired, failure)
* **`Purchase` category** — standard payment events that also fire on subscription billing cycles, and include a `subscription` object in the payload

<thead>
  <tr>
    <th>
      Event Type
    </th>

    <th>
      Category
    </th>

    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Subscription Created
    </td>

    <td>
      Subscription
    </td>

    <td>
      A subscription was purchased and activated for the first time.
    </td>
  </tr>

  <tr>
    <td>
      Subscription Canceled
    </td>

    <td>
      Subscription
    </td>

    <td>
      A subscription was canceled by the customer or merchant. Includes a 

      `reason`

       field.
    </td>
  </tr>

  <tr>
    <td>
      Subscription Expired
    </td>

    <td>
      Subscription
    </td>

    <td>
      The subscription can no longer be renewed (e.g. plan deactivated or max duration reached).
    </td>
  </tr>

  <tr>
    <td>
      Subscription Failure
    </td>

    <td>
      Subscription
    </td>

    <td>
      A renewal payment failed, preventing the subscription from being created or renewed.
    </td>
  </tr>

  <tr>
    <td>
      Settled
    </td>

    <td>
      Purchase
    </td>

    <td>
      A subscription billing payment completed successfully. Includes a 

      `subscription`

       object.
    </td>
  </tr>

  <tr>
    <td>
      Card Payment Authorized
    </td>

    <td>
      Purchase
    </td>

    <td>
      A subscription renewal card was authorized but not yet captured. Includes a 

      `subscription`

       object.
    </td>
  </tr>

  <tr>
    <td>
      Card Payment Declined
    </td>

    <td>
      Purchase
    </td>

    <td>
      A subscription renewal card was declined by the issuing bank.
    </td>
  </tr>
</tbody>

---

## Sample Webhook Payloads

### Subscription Lifecycle Events

These events use the `Subscription` category and contain subscription-specific data.

**`Subscription Created`**

```json Subscription Created
// Sent when a customer pays for a subscription for the first time
{
  "eventType": "Subscription Created",
  "category": "Subscription",
  "created": "2025-04-28T20:28:08.289Z",
  "data": {
    "planCode": "music_access",
    "planName": "creator1234",
    "subscriptionId": "680fe4d832ddccc1ee91885e",
    "customerId": "cust_abc123",
    "amount": {
      "cents": 500,
      "currency": "USD"
    },
    "interval": "Monthly",
    "fundingMethod": "Card",
    "webhookInfo": {
      "item": "sword"
    }
  }
}
```

**`Subscription Canceled`**

```json Subscription Canceled
// Sent when a customer or merchant cancels a subscription
{
  "eventType": "Subscription Canceled",
  "category": "Subscription",
  "created": "2025-04-28T20:33:05.322Z",
  "data": {
    "planCode": "music_access",
    "planName": "creator1234",
    "subscriptionId": "67d07938a899c293e0ae2147",
    "customerId": "cust_abc123",
    "amount": {
      "cents": 500,
      "currency": "USD"
    },
    "interval": "Monthly",
    "fundingMethod": "Card",
    "webhookInfo": {
      "item": "sword"
    },
    "reason": "Customer has canceled subscription"
  }
}
```

**`Subscription Expired`**

```json Subscription Expired
// Sent when a subscription can no longer be renewed
{
  "eventType": "Subscription Expired",
  "category": "Subscription",
  "created": "2025-04-28T20:35:00.000Z",
  "data": {
    "planCode": "music_access",
    "planName": "creator1234",
    "subscriptionId": "67d07938a899c293e0ae2147",
    "customerId": "cust_abc123",
    "amount": {
      "cents": 500,
      "currency": "USD"
    },
    "interval": "Monthly",
    "fundingMethod": "Card",
    "webhookInfo": {
      "item": "sword"
    },
    "reason": "Subscription has expired"
  }
}
```

**`Subscription Failure`**

```json Subscription Failure
// Sent when a renewal payment fails and the subscription cannot be renewed
{
  "eventType": "Subscription Failure",
  "category": "Subscription",
  "created": "2025-04-28T20:36:00.000Z",
  "data": {
    "planCode": "music_access",
    "planName": "creator1234",
    "subscriptionId": "67d07938a899c293e0ae2147",
    "customerId": "cust_abc123",
    "amount": {
      "cents": 500,
      "currency": "USD"
    },
    "interval": "Monthly",
    "fundingMethod": "Card",
    "webhookInfo": {
      "item": "sword"
    }
  }
}
```

### Subscription Payment Events

These events use the `Purchase` category and include a `subscription` object containing the full subscription and plan details.

**`Settled`**

```json Settled
// Sent when a subscription billing payment completes; funds are in your settlement wallet
{
  "eventType": "Settled",
  "category": "Purchase",
  "created": "2025-04-28T20:28:10.894Z",
  "data": {
    "id": "db746ccf-6dce-4019-b34b-b35a957cb5aa",
    "signature": "db746ccf6dce4019b34bb35a957cb5aa", // settlement reference; only present on advanced stablecoin settlement paths
    "webhookInfo": {
      "item": "sword"
    },
    "subtotal": {
      "cents": 500,
      "currency": "USD"
    },
    "fees": {
      "cents": 46,
      "currency": "USD"
    },
    // gasFees is only non-zero on advanced stablecoin settlement paths; otherwise 0
    "gasFees": {
      "cents": 0,
      "currency": "USD"
    },
    "chargebackProtectionFees": {
      "cents": 0,
      "currency": "USD"
    },
    "total": {
      "cents": 546,
      "currency": "USD"
    },
    "subscription": {
      "_id": "680fe4d832ddccc1ee91885e",
      "customer": "66ce47a1e487adc8f4ab0d46",
      "merchant": "66311727a26b3cb28faaf97d",
      "plan": {
        "amount": {
          "cents": 500,
          "currency": "USD"
        },
        "_id": "67bf86d03716ba82ce5cd096",
        "merchant": "66311727a26b3cb28faaf97d",
        "name": "creator1234",
        "code": "music_access",
        "interval": "Monthly",
        "duration": 12,
        "description": "Monthly subscription for fans to gain access to listen to Creator 1234 songs",
        "active": true,
        "__v": 0
      },
      "cardProcessor": "mock",
      "reference": "f008bb21-f6a1-4947-b271-90e78638f379",
      "nextPaymentAt": "2025-05-28T20:28:08.164Z",
      "status": "Active",
      "webhookInfo": {
        "item": "sword"
      },
      "createdAt": "2025-04-28T20:28:08.169Z",
      "updatedAt": "2025-04-28T20:28:08.169Z",
      "__v": 0
    },
    "merchantId": "testtest",
    "customerId": "cust_abc123",
    "rawCustomerId": "cust_abc123"
  }
}
```

**`Card Payment Authorized`**

```json Card Payment Authorized
// Sent when a subscription renewal card is authorized but not yet captured
{
  "eventType": "Card Payment Authorized",
  "category": "Purchase",
  "created": "2025-04-28T20:31:19.543Z",
  "data": {
    "webhookInfo": {
      "item": "sword"
    },
    "subtotal": {
      "cents": 500,
      "currency": "USD"
    },
    "fees": {
      "cents": 46,
      "currency": "USD"
    },
    "gasFees": {
      "cents": 0,
      "currency": "USD"
    },
    "chargebackProtectionFees": {
      "cents": 0,
      "currency": "USD"
    },
    "total": {
      "cents": 546,
      "currency": "USD"
    },
    "merchantId": "testtest",
    "id": "39ffc711-8023-46cf-b6ad-5dac81afec88",
    "subscription": {
      "_id": "67d07938a899c293e0ae2147",
      "customer": "67d07935a899c293e0ae2132",
      "merchant": "66311727a26b3cb28faaf97d",
      "plan": {
        "amount": {
          "cents": 500,
          "currency": "USD"
        },
        "_id": "67bf86d03716ba82ce5cd096",
        "merchant": "66311727a26b3cb28faaf97d",
        "name": "creator1234",
        "code": "music_access",
        "interval": "Monthly",
        "duration": 12,
        "description": "Monthly subscription for fans to gain access to listen to Creator 1234 songs",
        "active": true,
        "__v": 0
      },
      "cardProcessor": "mock",
      "reference": "148a2d77-c025-4c48-bccb-f8474ffcf903",
      "nextPaymentAt": "2025-05-11T17:56:08.261Z",
      "status": "Active",
      "webhookInfo": {
        "item": "sword"
      },
      "createdAt": "2025-03-11T17:56:08.262Z",
      "updatedAt": "2025-04-11T20:30:00.146Z",
      "__v": 0
    },
    "customerId": "cust_abc123",
    "rawCustomerId": "cust_abc123"
  }
}
```

**`Card Payment Declined`**

```json Card Payment Declined
// Sent when a subscription renewal card is declined by the issuing bank
{
  "eventType": "Card Payment Declined",
  "category": "Purchase",
  "created": "2025-04-28T20:21:50.163Z",
  "data": {
    "webhookInfo": {
      "item": "sword"
    },
    "subtotal": {
      "cents": 500,
      "currency": "USD"
    },
    "fees": {
      "cents": 46,
      "currency": "USD"
    },
    "gasFees": {
      "cents": 0,
      "currency": "USD"
    },
    "chargebackProtectionFees": {
      "cents": 0,
      "currency": "USD"
    },
    "total": {
      "cents": 546,
      "currency": "USD"
    },
    "merchantId": "testtest",
    "id": "bce7ca59-4bcc-43c3-95f1-51f2858b0bd2",
    "declineCode": "59",
    "declineDescription": "The transaction is suspected of fraud.",
    "customerId": "cust_abc123",
    "rawCustomerId": "cust_abc123"
  }
}
```

---

## Schema

### Subscription Lifecycle Event Schema

Applies to: `Subscription Created`, `Subscription Canceled`, `Subscription Expired`, `Subscription Failure`

**`Schema`**

```json Schema
{
  "eventType": "string",
  "category": "Subscription",
  "created": "string (ISO 8601)",
  "data": {
    "planCode": "string",
    "planName": "string",
    "subscriptionId": "string",
    "customerId": "string",
    "amount": { "cents": "number", "currency": "string" },
    "interval": "string (Monthly | Yearly | Weekly | Daily)",
    "fundingMethod": "string (Card)",
    "webhookInfo": { "key": "value" },
    "reason": "string (optional — present on Canceled and Expired events)"
  }
}
```

### Subscription Payment Event Schema

Applies to: `Settled`, `Card Payment Authorized`, `Card Payment Declined` (when triggered by a subscription billing cycle)

**`Schema`**

```json Schema
{
  "eventType": "string",
  "category": "Purchase",
  "created": "string (ISO 8601)",
  "data": {
    "id": "string",
    "signature": "string (present on Settled)",
    "webhookInfo": { "key": "value" },
    "subtotal": { "cents": "number", "currency": "string" },
    "fees": { "cents": "number", "currency": "string" },
    "gasFees": { "cents": "number", "currency": "string" },
    "chargebackProtectionFees": { "cents": "number", "currency": "string" },
    "total": { "cents": "number", "currency": "string" },
    "merchantId": "string",
    "customerId": "string",
    "rawCustomerId": "string",
    "declineCode": "string (present on Card Payment Declined)",
    "declineDescription": "string (present on Card Payment Declined)",
    "subscription": {
      "_id": "string",
      "status": "string (Active | Canceled | Expired)",
      "nextPaymentAt": "string (ISO 8601)",
      "plan": {
        "code": "string",
        "name": "string",
        "interval": "string",
        "duration": "number",
        "amount": { "cents": "number", "currency": "string" }
      },
      "webhookInfo": { "key": "value" }
    }
  }
}
```