> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vantio.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration & Settings

> Configure your Vantio account, programs, and API settings

## 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

<Warning>
  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.
</Warning>

### 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:

<ResponseField name="Commission Rate" type="number" required>
  The percentage commission ambassadors earn on referrals. Can be a flat rate or tiered structure.

  Example: `10` for 10% commission
</ResponseField>

<ResponseField name="Payout Schedule" type="string" required>
  How often ambassadors receive payouts. Options:

  * `weekly` - Weekly payouts
  * `biweekly` - Every two weeks
  * `monthly` - Monthly payouts
  * `manual` - Manual payouts only
</ResponseField>

<ResponseField name="Minimum Payout" type="number" required>
  Minimum earning amount required before payout is processed.

  Example: `5000` for \$50.00 minimum
</ResponseField>

## 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:

```bash theme={null}
# .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:

```javascript theme={null}
// 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:

<ResponseField name="Payment Provider" type="string" required>
  Integration with payment providers (Stripe, PayPal, etc.)
</ResponseField>

<ResponseField name="Payout Method" type="string" required>
  How ambassadors receive payments:

  * `bank_transfer` - Direct bank transfer
  * `paypal` - PayPal payment
  * `check` - Physical check
</ResponseField>

## 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:

```javascript theme={null}
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:

```javascript theme={null}
// 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

* Review [API Authentication](/essentials/markdown) for authentication setup
* Check [Code Examples](/essentials/code) for integration patterns
* Explore [Integration Patterns](/essentials/reusable-snippets) for reusable code