Query Card Remaining Limits

Overview

Use this endpoint to get the remaining spending limits of a specific card. This helps you monitor how much spending capacity is left for daily, weekly, monthly, and lifetime intervals, enabling proactive limit management and spending control.

NOTE: This API is offered on a client-by-client approval basis. Speak to your account manager to check eligibility.

Resource Access

Production (api.ahrvo.network)

GET https://api.ahrvo.network/card/issuance/api/issuing/spending-control/v2/share-card-remaining-limit

Staging (gateway.ahrvo.network)

GET https://gateway.ahrvo.network/card/issuance/api/issuing/spending-control/v2/share-card-remaining-limit

---

Request Headers

Header	Value	Required	Description
Accept	application/json	Yes	Content type for the response
Authorization	Bearer {access_token}	Yes	Bearer token for authentication
x-api-key	API Key	Yes	API key for authentication

Query Parameters

Parameter	Type	Required	Description
card_id	string	Yes	A unique ID of the card

Response

Success Response (200 OK)

{
  "code": "SUCCESS",
  "data": {
    "daily_limit": "1500.00",
    "weekly_limit": "5000.00",
    "monthly_limit": "18000.00",
    "lifetime_limit": "95000.00"
  }
}

Response Fields

Field	Type	Description
code	string	Status string indicating the result. "SUCCESS" refers to a successful query
data	object	Response data object
data.daily_limit	string	The remaining amount allowed for the card to spend today (in USD)
data.weekly_limit	string	The remaining amount allowed for the card to spend this week (in USD)
data.monthly_limit	string	The remaining amount allowed for the card to spend this month (in USD)
data.lifetime_limit	string	The remaining amount allowed for the card to spend in its lifetime (in USD)

Error Responses

• 400 Bad Request: Invalid card_id parameter
• 401 Unauthorized: Invalid or missing authentication token
• 403 Forbidden: Card issuance feature not enabled for this account
• 404 Not Found: Card does not exist

Code Examples

cURL

curl -X GET \
  'https://gateway.ahrvo.network/card/issuance/api/issuing/spending-control/v2/share-card-remaining-limit?card_id=card201907021723076245' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'x-api-key: YOUR_API_KEY'

Python

import requests

url = "https://gateway.ahrvo.network/card/issuance/api/issuing/spending-control/v2/share-card-remaining-limit"
headers = {
    "Accept": "application/json",
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "x-api-key": "YOUR_API_KEY"
}
params = {
    "card_id": "card201907021723076245"
}

response = requests.get(url, headers=headers, params=params)
result = response.json()

if result['code'] == 'SUCCESS':
    limits = result['data']
    
    print(f"Remaining Spending Limits:")
    print(f"  Daily: ${limits['daily_limit']}")
    print(f"  Weekly: ${limits['weekly_limit']}")
    print(f"  Monthly: ${limits['monthly_limit']}")
    print(f"  Lifetime: ${limits['lifetime_limit']}")
else:
    print(f"Failed to query limits: {result}")

JavaScript (Node.js)

const axios = require('axios');

const url = 'https://gateway.ahrvo.network/card/issuance/api/issuing/spending-control/v2/share-card-remaining-limit';
const headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
  'x-api-key': 'YOUR_API_KEY'
};
const params = {
  card_id: 'card201907021723076245'
};

axios.get(url, { headers, params })
  .then(response => {
    const result = response.data;
    
    if (result.code === 'SUCCESS') {
      const limits = result.data;
      
      console.log('Remaining Spending Limits:');
      console.log(`  Daily: $${limits.daily_limit}`);
      console.log(`  Weekly: $${limits.weekly_limit}`);
      console.log(`  Monthly: $${limits.monthly_limit}`);
      console.log(`  Lifetime: $${limits.lifetime_limit}`);
    }
  })
  .catch(error => {
    console.error('Failed to query limits:', error.response.data);
  });

Usage Notes

• Real-Time Data: Remaining limits reflect current spending and reset according to their intervals
• Limit Periods: Daily (24 hours), Weekly (7 days), Monthly (30 days), Lifetime (card lifetime)
• All Amounts: Returned amounts are in USD
• Negative Values: Not returned - minimum remaining is 0.00
• Multiple Checks: You can query limits as often as needed

Common Use Cases

Check Limits Before Large Purchase

Verify sufficient remaining limit before attempting a large transaction:

def check_limit_for_purchase(card_id, purchase_amount):
    """
    Check if card has sufficient remaining limit for a purchase
    """
    print(f"\nChecking limits for purchase of ${purchase_amount}")
    
    # Query remaining limits
    response = query_card_remaining_limits(card_id)
    
    if response['code'] == 'SUCCESS':
        limits = response['data']
        
        daily_remaining = float(limits['daily_limit'])
        weekly_remaining = float(limits['weekly_limit'])
        monthly_remaining = float(limits['monthly_limit'])
        lifetime_remaining = float(limits['lifetime_limit'])
        
        print(f"\nRemaining Limits:")
        print(f"  Daily: ${daily_remaining}")
        print(f"  Weekly: ${weekly_remaining}")
        print(f"  Monthly: ${monthly_remaining}")
        print(f"  Lifetime: ${lifetime_remaining}")
        
        # Check if purchase is within all limits
        checks = {
            'daily': daily_remaining >= purchase_amount,
            'weekly': weekly_remaining >= purchase_amount,
            'monthly': monthly_remaining >= purchase_amount,
            'lifetime': lifetime_remaining >= purchase_amount
        }
        
        print(f"\nPurchase Validation:")
        for period, passed in checks.items():
            status = "✓" if passed else "✗"
            print(f"  {status} {period.title()}: {'PASS' if passed else 'FAIL'}")
        
        if all(checks.values()):
            print(f"\n✓ Purchase of ${purchase_amount} is within all limits")
            return {
                'allowed': True,
                'remaining_limits': limits
            }
        else:
            failed_checks = [k for k, v in checks.items() if not v]
            print(f"\n✗ Purchase exceeds {', '.join(failed_checks)} limit(s)")
            return {
                'allowed': False,
                'failed_checks': failed_checks,
                'remaining_limits': limits
            }
    else:
        print(f"Failed to query limits: {response}")
        return {
            'allowed': False,
            'error': response
        }

# Example usage
result = check_limit_for_purchase('card201907021723076245', 800.00)

Monitor Multiple Cards

Check remaining limits for all cards in a department:

async function monitorDepartmentCardLimits(cards) {
  console.log('\n=== Department Card Limit Monitor ===\n');
  
  const lowLimitCards = [];
  const alerts = [];
  
  for (const card of cards) {
    try {
      const response = await queryCardRemainingLimits(card.card_id);
      
      if (response.code === 'SUCCESS') {
        const limits = response.data;
        const dailyRemaining = parseFloat(limits.daily_limit);
        const dailyTotal = parseFloat(card.daily_limit_total);
        
        const utilizationPercent = ((dailyTotal - dailyRemaining) / dailyTotal) * 100;
        
        console.log(`Card: ${card.cardholder_name}`);
        console.log(`  Daily: $${dailyRemaining} / $${dailyTotal} (${utilizationPercent.toFixed(1)}% used)`);
        console.log(`  Weekly: $${limits.weekly_limit}`);
        console.log(`  Monthly: $${limits.monthly_limit}`);
        
        // Check for low limits (less than 20% remaining)
        if (utilizationPercent > 80) {
          console.log(`  🔴 WARNING: Low remaining limit!\n`);
          
          lowLimitCards.push({
            card_id: card.card_id,
            cardholder_name: card.cardholder_name,
            daily_remaining: dailyRemaining,
            utilization: utilizationPercent
          });
          
          alerts.push({
            type: 'low_limit',
            card_id: card.card_id,
            cardholder: card.cardholder_name,
            remaining: dailyRemaining,
            utilization: utilizationPercent
          });
        } else if (utilizationPercent > 50) {
          console.log(`  🟡 NOTICE: Moderate usage\n`);
        } else {
          console.log(`  ✓ Normal usage\n`);
        }
      }
    } catch (error) {
      console.error(`  ✗ Error querying card: ${error.message}\n`);
    }
  }
  
  // Summary
  console.log(`=== Monitoring Summary ===`);
  console.log(`Total Cards: ${cards.length}`);
  console.log(`Low Limit Alerts: ${lowLimitCards.length}`);
  
  if (lowLimitCards.length > 0) {
    console.log('\nCards requiring attention:');
    lowLimitCards.forEach(card => {
      console.log(`  • ${card.cardholder_name}: $${card.daily_remaining} remaining (${card.utilization.toFixed(1)}% used)`);
    });
  }
  
  return {
    total_cards: cards.length,
    low_limit_count: lowLimitCards.length,
    low_limit_cards: lowLimitCards,
    alerts: alerts
  };
}

// Example usage
const departmentCards = [
  {
    card_id: 'card201907021723076245',
    cardholder_name: 'John Doe',
    daily_limit_total: '2000.00'
  },
  {
    card_id: 'card201907021723076246',
    cardholder_name: 'Jane Smith',
    daily_limit_total: '1500.00'
  }
];

const report = await monitorDepartmentCardLimits(departmentCards);

Daily Limit Report

Generate a daily report of card spending capacity:

def generate_daily_limit_report(card_list):
    """
    Generate comprehensive daily limit report for cards
    """
    from datetime import datetime
    
    print(f"\n=== Daily Card Limit Report ===")
    print(f"Generated: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}\n")
    
    report_data = []
    total_remaining = 0
    
    for card in card_list:
        try:
            response = query_card_remaining_limits(card['card_id'])
            
            if response['code'] == 'SUCCESS':
                limits = response['data']
                daily_remaining = float(limits['daily_limit'])
                daily_total = float(card['daily_limit_total'])
                
                spent_today = daily_total - daily_remaining
                utilization = (spent_today / daily_total * 100) if daily_total > 0 else 0
                
                card_data = {
                    'cardholder': card['cardholder_name'],
                    'department': card['department'],
                    'daily_total': daily_total,
                    'spent_today': spent_today,
                    'remaining': daily_remaining,
                    'utilization': utilization
                }
                
                report_data.append(card_data)
                total_remaining += daily_remaining
                
                # Print card details
                status = "🔴" if utilization > 80 else "🟡" if utilization > 50 else "🟢"
                print(f"{status} {card['cardholder_name']} ({card['department']})")
                print(f"   Limit: ${daily_total:.2f} | Spent: ${spent_today:.2f} | Remaining: ${daily_remaining:.2f}")
                print(f"   Utilization: {utilization:.1f}%\n")
        
        except Exception as e:
            print(f"✗ Error processing {card['cardholder_name']}: {e}\n")
    
    # Summary statistics
    print(f"=== Summary Statistics ===")
    print(f"Total Cards: {len(report_data)}")
    print(f"Total Remaining Daily Capacity: ${total_remaining:.2f}")
    
    if report_data:
        avg_utilization = sum(c['utilization'] for c in report_data) / len(report_data)
        high_usage = sum(1 for c in report_data if c['utilization'] > 80)
        
        print(f"Average Utilization: {avg_utilization:.1f}%")
        print(f"High Usage Cards (>80%): {high_usage}")
    
    # Department breakdown
    departments = {}
    for card in report_data:
        dept = card['department']
        if dept not in departments:
            departments[dept] = {
                'count': 0,
                'total_remaining': 0,
                'total_spent': 0
            }
        departments[dept]['count'] += 1
        departments[dept]['total_remaining'] += card['remaining']
        departments[dept]['total_spent'] += card['spent_today']
    
    print(f"\n=== Department Breakdown ===")
    for dept, stats in departments.items():
        print(f"{dept}:")
        print(f"  Cards: {stats['count']}")
        print(f"  Spent Today: ${stats['total_spent']:.2f}")
        print(f"  Remaining: ${stats['total_remaining']:.2f}")
    
    return {
        'generated_at': datetime.now().isoformat(),
        'cards': report_data,
        'total_remaining': total_remaining,
        'departments': departments
    }

# Example usage
cards = [
    {
        'card_id': 'card201907021723076245',
        'cardholder_name': 'John Doe',
        'department': 'Marketing',
        'daily_limit_total': '2000.00'
    },
    {
        'card_id': 'card201907021723076246',
        'cardholder_name': 'Jane Smith',
        'department': 'Sales',
        'daily_limit_total': '1500.00'
    },
    {
        'card_id': 'card201907021723076247',
        'cardholder_name': 'Bob Johnson',
        'department': 'Marketing',
        'daily_limit_total': '1000.00'
    }
]

report = generate_daily_limit_report(cards)

Spending Utilization Dashboard

Create a real-time utilization dashboard:

async function createUtilizationDashboard(cards) {
  console.log('\n╔════════════════════════════════════════════════════════════════╗');
  console.log('║           CARD SPENDING UTILIZATION DASHBOARD                  ║');
  console.log('╚════════════════════════════════════════════════════════════════╝\n');
  
  const utilizationData = [];
  
  for (const card of cards) {
    try {
      const response = await queryCardRemainingLimits(card.card_id);
      
      if (response.code === 'SUCCESS') {
        const limits = response.data;
        
        // Calculate utilization for each period
        const dailyUtil = ((card.daily_total - parseFloat(limits.daily_limit)) / card.daily_total) * 100;
        const weeklyUtil = ((card.weekly_total - parseFloat(limits.weekly_limit)) / card.weekly_total) * 100;
        const monthlyUtil = ((card.monthly_total - parseFloat(limits.monthly_limit)) / card.monthly_total) * 100;
        const lifetimeUtil = ((card.lifetime_total - parseFloat(limits.lifetime_limit)) / card.lifetime_total) * 100;
        
        const cardData = {
          name: card.name,
          daily: {
            remaining: parseFloat(limits.daily_limit),
            total: card.daily_total,
            utilization: dailyUtil
          },
          weekly: {
            remaining: parseFloat(limits.weekly_limit),
            total: card.weekly_total,
            utilization: weeklyUtil
          },
          monthly: {
            remaining: parseFloat(limits.monthly_limit),
            total: card.monthly_total,
            utilization: monthlyUtil
          },
          lifetime: {
            remaining: parseFloat(limits.lifetime_limit),
            total: card.lifetime_total,
            utilization: lifetimeUtil
          }
        };
        
        utilizationData.push(cardData);
        
        // Display card dashboard
        console.log(`┌─ ${card.name} ${'─'.repeat(60 - card.name.length)}`);
        console.log(`│`);
        
        const periods = ['daily', 'weekly', 'monthly', 'lifetime'];
        for (const period of periods) {
          const data = cardData[period];
          const bar = createProgressBar(data.utilization);
          const color = data.utilization > 80 ? '🔴' : data.utilization > 50 ? '🟡' : '🟢';
          
          console.log(`│  ${color} ${period.toUpperCase().padEnd(10)} ${bar} ${data.utilization.toFixed(1)}%`);
          console.log(`│     Remaining: $${data.remaining.toFixed(2)} / $${data.total.toFixed(2)}`);
          console.log(`│`);
        }
        
        console.log('└────────────────────────────────────────────────────────────────\n');
      }
    } catch (error) {
      console.error(`Error processing ${card.name}: ${error.message}\n`);
    }
  }
  
  return utilizationData;
}

function createProgressBar(percentage, width = 30) {
  const filled = Math.round((percentage / 100) * width);
  const empty = width - filled;
  return '[' + '█'.repeat(filled) + '░'.repeat(empty) + ']';
}

// Example usage
const cards = [
  {
    card_id: 'card201907021723076245',
    name: 'John Doe - Marketing',
    daily_total: 2000,
    weekly_total: 8000,
    monthly_total: 30000,
    lifetime_total: 200000
  },
  {
    card_id: 'card201907021723076246',
    name: 'Jane Smith - Sales',
    daily_total: 1500,
    weekly_total: 6000,
    monthly_total: 25000,
    lifetime_total: 150000
  }
];

const dashboard = await createUtilizationDashboard(cards);

Automated Limit Alert System

Set up automated alerts when limits are low:

def setup_limit_alert_system(cards, alert_threshold=20):
    """
    Monitor cards and send alerts when remaining limits fall below threshold
    
    Args:
        cards: List of card configurations
        alert_threshold: Percentage threshold for alerts (default 20%)
    """
    import time
    from datetime import datetime
    
    print(f"\n=== Automated Limit Alert System ===")
    print(f"Alert Threshold: {alert_threshold}%")
    print(f"Monitoring {len(cards)} cards...\n")
    
    alerts_sent = []
    
    while True:
        current_time = datetime.now().strftime('%H:%M:%S')
        print(f"[{current_time}] Checking card limits...")
        
        for card in cards:
            try:
                response = query_card_remaining_limits(card['card_id'])
                
                if response['code'] == 'SUCCESS':
                    limits = response['data']
                    
                    # Check each limit type
                    for limit_type in ['daily', 'weekly', 'monthly']:
                        remaining = float(limits[f'{limit_type}_limit'])
                        total = float(card[f'{limit_type}_limit_total'])
                        
                        remaining_percent = (remaining / total * 100) if total > 0 else 0
                        
                        if remaining_percent <= alert_threshold:
                            alert_key = f"{card['card_id']}_{limit_type}_{datetime.now().date()}"
                            
                            if alert_key not in alerts_sent:
                                print(f"  🚨 ALERT: {card['cardholder_name']}")
                                print(f"     {limit_type.title()} limit low: ${remaining:.2f} ({remaining_percent:.1f}% remaining)")
                                
                                # Send alert notification
                                send_alert_notification({
                                    'card_id': card['card_id'],
                                    'cardholder': card['cardholder_name'],
                                    'limit_type': limit_type,
                                    'remaining': remaining,
                                    'total': total,
                                    'remaining_percent': remaining_percent,
                                    'timestamp': datetime.now().isoformat()
                                })
                                
                                alerts_sent.append(alert_key)
            
            except Exception as e:
                print(f"  ✗ Error checking {card['cardholder_name']}: {e}")
        
        print(f"[{current_time}] Check complete. Waiting 5 minutes...\n")
        time.sleep(300)  # Check every 5 minutes

def send_alert_notification(alert_data):
    """Send alert via email/SMS/Slack"""
    # Implementation depends on your notification system
    print(f"     📧 Alert notification sent")

# Example usage
cards_to_monitor = [
    {
        'card_id': 'card201907021723076245',
        'cardholder_name': 'John Doe',
        'daily_limit_total': '2000.00',
        'weekly_limit_total': '8000.00',
        'monthly_limit_total': '30000.00'
    }
]

# Run in background or scheduled job
# setup_limit_alert_system(cards_to_monitor, alert_threshold=20)

Budget Planning Assistant

Help plan future spending based on remaining limits:

async function budgetPlanningAssistant(cardId, plannedExpenses) {
  console.log('\n=== Budget Planning Assistant ===\n');
  
  try {
    // Get current remaining limits
    const response = await queryCardRemainingLimits(cardId);
    
    if (response.code === 'SUCCESS') {
      const limits = response.data;
      
      console.log('Current Remaining Limits:');
      console.log(`  Daily: $${limits.daily_limit}`);
      console.log(`  Weekly: $${limits.weekly_limit}`);
      console.log(`  Monthly: $${limits.monthly_limit}`);
      console.log(`  Lifetime: $${limits.lifetime_limit}\n`);
      
      // Calculate total planned expenses
      const totalPlanned = plannedExpenses.reduce((sum, exp) => sum + exp.amount, 0);
      
      console.log(`Planned Expenses (${plannedExpenses.length} items):`);
      plannedExpenses.forEach(exp => {
        console.log(`  • ${exp.description}: $${exp.amount.toFixed(2)}`);
      });
      console.log(`  Total: $${totalPlanned.toFixed(2)}\n`);
      
      // Check feasibility
      const dailyRemaining = parseFloat(limits.daily_limit);
      const weeklyRemaining = parseFloat(limits.weekly_limit);
      const monthlyRemaining = parseFloat(limits.monthly_limit);
      
      const feasibility = {
        daily: dailyRemaining >= totalPlanned,
        weekly: weeklyRemaining >= totalPlanned,
        monthly: monthlyRemaining >= totalPlanned
      };
      
      console.log('Feasibility Check:');
      console.log(`  ${feasibility.daily ? '✓' : '✗'} Daily limit: ${feasibility.daily ? 'SUFFICIENT' : 'INSUFFICIENT'}`);
      console.log(`  ${feasibility.weekly ? '✓' : '✗'} Weekly limit: ${feasibility.weekly ? 'SUFFICIENT' : 'INSUFFICIENT'}`);
      console.log(`  ${feasibility.monthly ? '✓' : '✗'} Monthly limit: ${feasibility.monthly ? 'SUFFICIENT' : 'INSUFFICIENT'}\n`);
      
      if (feasibility.daily && feasibility.weekly && feasibility.monthly) {
        const afterDaily = dailyRemaining - totalPlanned;
        const afterWeekly = weeklyRemaining - totalPlanned;
        const afterMonthly = monthlyRemaining - totalPlanned;
        
        console.log('✓ All planned expenses can be accommodated');
        console.log('\nRemaining After Expenses:');
        console.log(`  Daily: $${afterDaily.toFixed(2)}`);
        console.log(`  Weekly: $${afterWeekly.toFixed(2)}`);
        console.log(`  Monthly: $${afterMonthly.toFixed(2)}`);
        
        return {
          feasible: true,
          total_planned: totalPlanned,
          remaining_after: {
            daily: afterDaily,
            weekly: afterWeekly,
            monthly: afterMonthly
          }
        };
      } else {
        const blockers = [];
        if (!feasibility.daily) blockers.push('daily');
        if (!feasibility.weekly) blockers.push('weekly');
        if (!feasibility.monthly) blockers.push('monthly');
        
        console.log(`✗ Cannot accommodate all expenses`);
        console.log(`  Blocked by: ${blockers.join(', ')} limit(s)`);
        console.log('\nRecommendations:');
        console.log('  1. Spread expenses across multiple days/weeks');
        console.log('  2. Request limit increase');
        console.log('  3. Prioritize essential expenses');
        
        return {
          feasible: false,
          total_planned: totalPlanned,
          blockers: blockers
        };
      }
    }
  } catch (error) {
    console.error('Budget planning failed:', error);
    throw error;
  }
}

// Example usage
const plannedExpenses = [
  { description: 'Software subscription', amount: 299.00 },
  { description: 'Office supplies', amount: 150.00 },
  { description: 'Team lunch', amount: 200.00 },
  { description: 'Conference ticket', amount: 500.00 }
];

const plan = await budgetPlanningAssistant(
  'card201907021723076245',
  plannedExpenses
);

Best Practices

• Regular Monitoring: Check limits regularly, especially for high-usage cards
• Proactive Alerts: Set up alerts when remaining limits fall below thresholds (e.g., 20%)
• Pre-Purchase Checks: Query limits before attempting large transactions
• Dashboard Integration: Display remaining limits in your card management dashboard
• Department Reports: Generate regular reports for department managers
• Limit Planning: Use remaining limits to plan future spending

Understanding Limit Periods

Daily Limit

• Resets every 24 hours
• Use for day-to-day spending control
• Most volatile, changes frequently

Weekly Limit

• Resets every 7 days
• Good for short-term planning
• Smooths out daily fluctuations

Monthly Limit

• Resets every 30 days
• Aligns with budget cycles
• Best for monthly budget management

Lifetime Limit

• Never resets (until card closure)
• Provides overall spending cap
• Useful for long-term tracking

Related Endpoints

• Control Card Spending - Set or update spending limits
• Create a Card - Create cards with initial spending limits
• Query Card Details - View complete card information including limits
• Card Transaction History - Review spending that reduced limits

Troubleshooting

Card Not Found (404)

• Cause: Invalid card_id or card doesn't exist
• Solution:
  • Verify the card ID is correct
  • Ensure the card was created successfully
  • Check if card was closed or deleted

Unexpected Limit Values

• Cause: Recent transactions haven't been processed yet
• Solution:
  • Wait a few seconds and query again
  • Check transaction history for pending transactions
  • Contact support if discrepancy persists

Zero Remaining Limits

• Cause: Card has reached spending limit for the period
• Solution:
  • Wait for the period to reset (daily/weekly/monthly)
  • Increase the spending limit if needed
  • Use alternative payment method

Security Considerations

• Access Control: Restrict limit queries to authorized users
• Privacy: Remaining limits reveal spending patterns - protect this data
• Monitoring: Log all limit queries for audit purposes
• Rate Limiting: Implement reasonable query intervals to avoid abuse

Interactive API Explorer