Overview

Spinwheel’s Statement Subscription Service enables your platform to receive near real-time notifications when key financial information—such as statement balances or payment due dates—updates for your users. This ensures your users stay informed and your app remains proactive and responsive.

Key Benefits

✅ Real-Time Notifications for updated statement information

📅 Due Date & Statement Balance Awareness to power reminders or triggers

🔄 Easy Subscription Management via standardized APIs

Getting Started

Step 1: Subscribe to a Statement Update

Use the following endpoint to subscribe a user to statement update events:

POST /v1/users/{userId}/liabilities/subscriptions

Example Request Body:

{  
  "creditCards": [  
    {  
      "id": "fb444634-40a8-4a62-849d-4e2db7b8a9ad",  
      "subscriptions": [  
        { "capability": "STATEMENT_SUMMARY" }  
      ]  
    }  
  ]  
}

Note: Each user/card pair can have only one active subscription per capability.

🚧

If a subscription already exists, a 409 conflict will be returned.

Step 2 (Optional): List Active Subscriptions

To verify existing subscriptions or confirm that one has been successfully created, use:

GET /v1/users/{userId}/liabilities/subscriptions

This returns a list of active subscriptions, including the type and associated credit card or liabilityId.

Step 3: Handle Real-Time Webhook Notifications

Once a user is subscribed, Spinwheel will send webhook notifications whenever statement data points are updated.

Sample Payload – STATEMENT_SUMMARY_NOTIFICATION

{
  "webhookId": "1714461341615-0",
  "subscriptionId": "28ddf73b-bd93-4c06-afa5-fd4e3994d23f",
  "eventType": "STATEMENT_SUMMARY_NOTIFICATION",
  "userId": "abc123",
  "data": {
    "creditCards": [
      {
        "creditCardId": "7025c075-e92d-46fa-85e5-ac31ca667079",
        "statementSummary": {
          "statementBalance": 3194,
          "minimumPaymentAmount": 101,
          "dueDate": "2021-09-08T00:00:00.000Z",
          "lastPaymentAmount": 400,
          "lastPaymentDateWithFormat": {
            "value": "2021-08-21",
            "format": "YYYY-MM-DD"
          },
          "statementDateWithFormat": {
            "value": "2021-08-08",
            "format": "YYYY-MM-DD"
          },
          "overduePeriod": "NOT_OVERDUE",
          "amountPastDue": 700,
          "dueDateWithFormat": {
            "value": "2021-09-08",
            "format": "YYYY-MM-DD"
          },
          "updatedOn": 1719584284061
        }
      }
    ]
  }
}

📘

The payload only includes fields that have recently changed

Step 4: Optionally Trigger On-Demand Refreshes (Link to Full Guide)

You can request a real-time update for a user's statement data outside of the scheduled subscription logic. This is helpful for user-driven interactions, such as when someone opens your app and wants the most current data.

This does not require a subscription to be in place and allows you to fetch fresh data on demand.

Step 5: Unsubscribe Liabilities From Statement Summary Subscriptions

You can delete existing subscriptions as needed—either to stop webhook notifications or to allow recreation of a new one (since only one subscription per type is allowed per liability).

Delete Subscription Endpoint

DELETE /v1/users/{userId}/liabilities/subscriptions

Example Request Body:

{  
  "subscriptionIds": ["your-subscription-id"]  
}