Recurring Payments API

The Recurring Payments API provides the operational infrastructure for managing subscription-based revenue models. It allows organizations to define sophisticated billing cycle parameters, configure automated dunning (retry) policies for failed transactions, and monitor the real-time status of all active subscriptions across the platform.

Operational Configuration

Audit Recurring Settings

Retrieve the global operational parameters governing recurring billing. This includes the current retry logic for failed payments and the timing offsets for subsequent billing cycles.

{
  "status": "success",
  "settings": {
    "retry_policy": "exponential_backoff",
    "max_retries": 5,
    "next_cycle_offset": "24 hours",
    "dunning_notifications": true
  }
}

Technical Implementation

curl --location --request GET \
'https://api.hub.donutwork.com/2026-02-01/recurring-payments/settings.json' \
--header 'Authorization: Bearer YOUR_API_TOKEN'

try {
  const config = await sdk.recurringPayments.getSettings();
  console.log(`Billing Policy: ${config.settings.retry_policy} (Max Retries: ${config.settings.max_retries})`);
} catch (error) {
  console.error(`Fetch Failed: ${error.message}`);
}

Subscription Lifecycle Monitoring

Audit Active Subscriptions

Retrieve a comprehensive inventory of all subscriptions currently managed by the recurring payment engine. This endpoint provides crucial visibility into renewal dates, customer associations, and current billing health.

{
  "type": "RecurringSubscriptions",
  "count": 1250,
  "per_page": 100,
  "elements": [
    {
      "id": "67bdf...",
      "customerId": "66a15...",
      "subscription_reference": "sub_premium_9921",
      "status": "active",
      "next_renewal_date": "2026-04-01T00:00:00Z",
      "last_payment_status": "success"
    }
  ]
}

Implementation

const filters = { page: 1, size: 50 };
try {
  const activeSubs = await sdk.recurringPayments.listSubscriptions(filters);
  activeSubs.elements.forEach(sub => {
    console.log(`Subscription ${sub.id}: Renewal due on ${sub.next_renewal_date}`);
  });
} catch (error) {
  console.error(`Telemetry Error: ${error.message}`);
}