Skip to main content

​
Overview

This guide covers how to configure your Vantio account, set up programs, and customize settings for your referral system.

​
Account Settings

​
API Keys

Manage your API keys in the dashboard:
  1. Navigate to Settings → API Keys
  2. Click Create New API Key
  3. Give your key a descriptive name (e.g., “Production Server”, “Development”)
  4. Copy and store your key securely
API keys are only shown once when created. If you lose a key, you’ll need to create a new one and revoke the old one.

​
Webhook Configuration

Set up webhooks to receive real-time notifications:
  1. Go to Settings → Webhooks
  2. Click Add Webhook
  3. Enter your webhook URL
  4. Select events to subscribe to:
    • Referral created
    • Referral status changed
    • Earning created
    • Earning status changed

​
Program Configuration

​
Creating a Program

Programs organize your referral system. Each program can have:
  • Multiple student ambassadors
  • Unique commission rates
  • Custom settings and rules
Via Dashboard:
  1. Navigate to Programs
  2. Click Create New Program
  3. Configure:
    • Program name
    • Description
    • Commission structure
    • Payout settings

​
Program Settings

Configure program-specific settings:
​
Commission Rate
number
required
The percentage commission ambassadors earn on referrals. Can be a flat rate or tiered structure.Example: 10 for 10% commission
​
Payout Schedule
string
required
How often ambassadors receive payouts. Options:
  • weekly - Weekly payouts
  • biweekly - Every two weeks
  • monthly - Monthly payouts
  • manual - Manual payouts only
​
Minimum Payout
number
required
Minimum earning amount required before payout is processed.Example: 5000 for $50.00 minimum

​
API Configuration

​
Base URL

The Vantio API base URL depends on your environment:
  • Development: http://localhost:3000
  • Production: https://api.vantio.app (or your production URL)

​
Environment Variables

Store configuration in environment variables: 
# .env
VANTIO_API_KEY=sk_your_secret_key_here
VANTIO_BASE_URL=https://api.vantio.app
VANTIO_PROGRAM_ID=prog_123abc

​
Client Configuration

Configure your API client: 
// config/vantio.js
const config = {
  apiKey: process.env.VANTIO_API_KEY,
  baseURL: process.env.VANTIO_BASE_URL || 'http://localhost:3000',
  defaultProgramId: process.env.VANTIO_PROGRAM_ID,
  timeout: 30000, // 30 seconds
  retries: 3
};

module.exports = config;

​
Referral Settings

​
Status Workflow

Configure the referral status workflow:
  1. Pending - Initial status when referral is created
  2. Converted - Referred customer made a purchase
  3. Verified - Conversion verified by admin
  4. Rejected - Referral doesn’t meet criteria

​
Auto-Verification

Enable automatic verification for referrals:
  • Auto-verify on conversion - Automatically verify when status changes to converted
  • Require manual verification - All referrals require manual approval

​
Earning Settings

​
Commission Calculation

Configure how commissions are calculated:
  • Percentage-based - Fixed percentage of purchase amount
  • Tiered - Different rates based on volume
  • Fixed amount - Fixed commission per conversion

​
Payout Processing

Configure payout processing:
​
Payment Provider
string
required
Integration with payment providers (Stripe, PayPal, etc.)
​
Payout Method
string
required
How ambassadors receive payments:
  • bank_transfer - Direct bank transfer
  • paypal - PayPal payment
  • check - Physical check

​
Security Settings

​
API Key Rotation

Regularly rotate your API keys:
  1. Create a new API key
  2. Update your application to use the new key
  3. Test that everything works
  4. Revoke the old key

​
Rate Limiting

Be aware of API rate limits:
  • Standard Plan: 100 requests/minute
  • Pro Plan: 1000 requests/minute
  • Enterprise: Custom limits
Implement retry logic with exponential backoff: 
async function requestWithRetry(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      const response = await fetch(url, options);
      if (response.ok) return response;
      
      if (response.status === 429) {
        const delay = Math.pow(2, i) * 1000; // Exponential backoff
        await new Promise(resolve => setTimeout(resolve, delay));
        continue;
      }
      
      throw new Error(`Request failed: ${response.status}`);
    } catch (error) {
      if (i === maxRetries - 1) throw error;
    }
  }
}

​
Notification Settings

​
Email Notifications

Configure email notifications for:
  • New referrals
  • Status changes
  • Payout processed
  • Account activity

​
Webhook Notifications

Set up webhooks for real-time updates: 
// Example webhook handler
app.post('/webhooks/vantio', async (req, res) => {
  const { event, data } = req.body;
  
  switch (event) {
    case 'referral.created':
      await handleNewReferral(data);
      break;
    case 'earning.created':
      await handleNewEarning(data);
      break;
    case 'earning.paid':
      await handleEarningPaid(data);
      break;
  }
  
  res.json({ received: true });
});

​
Best Practices

  1. Use environment-specific keys - Separate keys for development and production
  2. Rotate keys regularly - Improve security by rotating API keys periodically
  3. Monitor usage - Track API usage to stay within rate limits
  4. Test webhooks - Use webhook testing tools to verify your endpoints
  5. Backup settings - Export and backup your configuration

​
Next Steps