Managing Subscriptions

Search, monitor, and manage your customer subscriptions.

Subscription Lifecycle

Subscriptions move through these states:

Subscription Status	Description	Trigger (Payment Status/Event)	Customer Access (Recomended)
Active	Subscription is in good standing. Payments are current and service is delivered.	Initial payment succeeded: Payment.Status = authorized/settled/OK Renewal payment succeeded: Payment.Status = authorized/settled/OK Recovery after retry:- Payment.Status = authorized/settled/OK	✅Yes, full access (entitled for the product/service)
Billing Retry (Redemption)	Payment on renewal failed, but failure is potentially recoverable (soft decline). System retries as per the strategy.	2nd + Payment Status = declined; Decline Type = soft_decline — Retry strategy engaged Time out of provider — Retry strategy engaged Examples: insufficient funds; timeout; issuer unavailable	✅Yes, access is typically retained (but merchant can revoke if needed.)
Cancelled	Subscription is terminated by user/admin or by hard payment failure No future renewals. User may have access until paid period ends, or access may end immediately.	User/admin/support cancellation:- Manual cancel via CRM Cancel request received via portal/API Immediate cancellation: Decline Type = hard_decline (e.g., stolen card, account closed, VSPS, R0/R1/R3 codes) Refund/void Fraud/alert event received (TC40/Ethoca/RDR/CRDN etc) Note: For scheduled cancellation, access continues until end of paid period. For immediate, access ends now.	✅ Access until end of period (scheduled); ❌No access (immediate)
Expired	Subscription is no longer active (billing ceased, term ended, all retries failed).	All retry attempts exhausted	❌ No access (product/service is revoked)
Paused (will not be in MVP stage)	The subscription is temporarily on hold (no billing occurs during the pause). This is a voluntary state initiated by the customer or admin, not directly tied to a payment failure.	– Applied when a user requests to pause their subscription (or an admin/business action pauses it) for a certain period. No new charges will be attempted during a pause interval. – A pause can be initiated only from Active (or possibly from the end of a trial);cannot pause an already canceled or expired subscription. The status changes to Paused for the duration of the pause.	❌ No access during the paused period.
Cancelation Pending	The state when the Subscription is cancelled, but the end of the cycle has not yet happened, from this state it transfers to Expired.	No further charges or retry attempts will happen	✅ Access until end of period (scheduled);

Retrieving Subscriptions

Get a Single Subscription

curl -X GET https://api.flintn.com/v1/subscriptions/sub_xyz789 \
  -H "X-Api-Key: pk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Response:

{
  "id": "sub_xyz789",
  "subscription_plan_id": "sp_abc123def456",
  "customer_id": "cust_123456",
  "status": "ACTIVE",
  "current_period_start": "2024-01-15T10:30:00Z",
  "current_period_end": "2024-02-15T10:30:00Z",
  "next_billing_date": "2024-02-15T10:30:00Z",
  "created_at": "2024-01-15T10:30:00Z"
}

Search Subscriptions

Search subscriptions with filters:

curl -X GET "https://api.flintn.com/v1/subscriptions?status=ACTIVE&customer_id=cust_123456" \
  -H "X-Api-Key: pk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Query Parameters:

Parameter	Description
status	Filter by status: ACTIVE, CANCELLED, EXPIRED, BILLING_RETRY
customer_id	Filter by customer ID
subscription_plan_id	Filter by plan ID
limit	Number of results (default: 20, max: 100)
offset	Pagination offset

Response:

{
  "data": [
    {
      "id": "sub_xyz789",
      "subscription_plan_id": "sp_abc123def456",
      "customer_id": "cust_123456",
      "status": "ACTIVE",
      "current_period_end": "2024-02-15T10:30:00Z"
    }
  ],
  "total": 1,
  "limit": 20,
  "offset": 0
}

Cancelling Subscriptions

Cancel Immediately

Cancel a subscription effective immediately:

curl -X POST https://api.flintn.com/v1/subscriptions/sub_xyz789/cancel \
  -H "X-Api-Key: pk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "cancel_at": "immediately"
  }'

Cancel at Period End

Allow the subscription to run until the current billing period ends:

curl -X POST https://api.flintn.com/v1/subscriptions/sub_xyz789/cancel \
  -H "X-Api-Key: pk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "cancel_at": "period_end"
  }'

Response:

{
  "id": "sub_xyz789",
  "status": "CANCELLED",
  "cancelled_at": "2024-01-20T15:00:00Z",
  "cancel_at_period_end": true,
  "current_period_end": "2024-02-15T10:30:00Z"
}

Monitoring via Dashboard

Subscription List

1. Log in to hub.flintn.com

2. Navigate to Subscriptions

3. View all subscriptions with status, customer, and plan details

Filtering and Search

Use the dashboard filters to:

• Filter by status (Active, Cancelled, Expired, Billing Retry)

• Search by customer email or ID

• Filter by subscription plan

• Sort by created date or next billing date

Subscription Details

Click on a subscription to view:

• Current status and billing period

• Customer information

• Plan details

• Payment history

• Retry attempts (if in BILLING_RETRY status)

Webhook Events

Monitor subscription changes in real-time:

Event	When Sent
SUBSCRIPTION_ACTIVATED	New subscription activated
SUBSCRIPTION_RENEWED	Subscription successfully renewed
SUBSCRIPTION_CANCELLED	Subscription cancelled
SUBSCRIPTION_EXPIRED	Subscription expired
SUBSCRIPTION_BILLING_RETRY	Failed payment retry attempt

See Configure Webhooks for setup.

Example: Handling Cancellation

app.post('/webhooks/flintn', (req, res) => {
  const event = req.body;

  if (event.type === 'SUBSCRIPTION_CANCELLED') {
    const subscriptionId = event.data.subscription_id;
    const customerId = event.data.customer_id;

    // Update your database
    // Send cancellation confirmation email
    // Revoke access at period end

    console.log(`Subscription ${subscriptionId} cancelled`);
  }

  res.status(200).send('OK');
});

Common Operations

Check if Subscription is Active

async function isSubscriptionActive(subscriptionId) {
  const response = await fetch(
    `https://api.flintn.com/v1/subscriptions/${subscriptionId}`,
    {
      headers: { 'X-Api-Key': process.env.FLINTN_API_KEY }
    }
  );

  const subscription = await response.json();
  return subscription.status === 'ACTIVE';
}

List Customer's Subscriptions

async function getCustomerSubscriptions(customerId) {
  const response = await fetch(
    `https://api.flintn.com/v1/subscriptions?customer_id=${customerId}`,
    {
      headers: { 'X-Api-Key': process.env.FLINTN_API_KEY }
    }
  );

  const result = await response.json();
  return result.data;
}

Handle Expiring Subscriptions

async function notifyExpiringSubscriptions() {
  const response = await fetch(
    `https://api.flintn.com/v1/subscriptions?status=ACTIVE`,
    {
      headers: { 'X-Api-Key': process.env.FLINTN_API_KEY }
    }
  );

  const { data: subscriptions } = await response.json();

  const soon = new Date();
  soon.setDate(soon.getDate() + 7); // 7 days from now

  const expiringSoon = subscriptions.filter(sub => {
    const endDate = new Date(sub.current_period_end);
    return endDate <= soon;
  });

  // Send reminder emails
  for (const sub of expiringSoon) {
    await sendRenewalReminder(sub.customer_id, sub);
  }
}

Best Practices

Graceful Cancellation

• Allow customers to cancel at period end rather than immediately

• Send confirmation emails with the effective cancellation date

• Provide easy re-subscription options

Monitoring Billing Retries

• Watch for SUBSCRIPTION_BILLING_RETRY events

• Consider reaching out to customers with payment issues

• Review retry strategy effectiveness periodically

Data Synchronization

• Use webhooks as the primary source of truth for subscription status

• Implement idempotent webhook handlers

• Store the subscription ID in your database for easy lookups

Next Steps

• Handling Failed Payments - Retry logic and dunning

• Retry Strategies - Configure automatic retries

• Transactions - View payment history