​
Overview

Edge API instances provide low-latency access to your Paygentic data by serving read requests from regions closer to your users. These endpoints are optimized for high-frequency read operations and can significantly improve your application’s performance.

​
Key Benefits

  • Lower Latency: Reduced response times by serving data from nearby regions
  • Higher Reliability: Automatic failover and redundancy across regions
  • Better Performance: Optimized for read-heavy workloads

​
Important Notes

  • Edge instances support read operations (GET requests) and regional usage recording
  • Most write operations (POST, PUT, DELETE) must use the main API at api.paygentic.io
  • Regional entitlement creation and usage event recording are supported on edge instances

​
Available Regions

RegionEndpoint
Global (Auto-routing)https://edge-api.paygentic.io
Asia Southhttps://asia-south1-edge-api.paygentic.io
Europe Westhttps://europe-west1-edge-api.paygentic.io

​
Using Edge Instances

The global edge endpoint automatically routes your request to the best available region: 
curl https://edge-api.paygentic.io/v0/customers?organizationId=org_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Regional Edge

For consistent routing to a specific region: 
curl https://europe-west1-edge-api.paygentic.io/v0/customers?organizationId=org_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Alternative: Header-Based Routing

You can also use headers with the main API domain: 
# Global edge routing
curl https://api.paygentic.io/v0/customers?organizationId=org_abc123 \
  -H "X-Paygentic-Edge: true" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Regional routing
curl https://api.paygentic.io/v0/customers?organizationId=org_abc123 \
  -H "X-Paygentic-Region: asia-south1" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Code Examples

// Read operations - use edge endpoint
const getCustomers = async (organizationId: string) => {
  const response = await fetch(`https://edge-api.paygentic.io/v0/customers?organizationId=${organizationId}`, {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  });
  return response.json();
};

// Write operations - use main API
const createCustomer = async (consumerId: string, merchantId: string) => {
  const response = await fetch('https://api.paygentic.io/v0/customers', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      consumerId: consumerId,
      merchantId: merchantId
    })
  });
  return response.json();
};

​
Regional Entitlements and Usage Recording

One of the key advantages of edge instances is their ability to handle regional entitlements and usage event recording with ultra-low latency. This is particularly valuable for applications that need to:
  • Create time-limited entitlements for users in specific regions
  • Record high-frequency usage events (API calls, compute usage, etc.)
  • Maintain regional compliance and data residency requirements

​
Creating Regional Entitlements

// Create a regional entitlement using the edge instance
const createRegionalEntitlement = async (merchantId: string, customerId: string, billableMetricId: string, quantity: number) => {
  const response = await fetch('https://europe-west1-edge-api.paygentic.io/v0/entitlements', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      merchantId: merchantId,
      customerId: customerId,
      entitlementData: [
        {
          billableMetricId: billableMetricId,
          quantity: quantity
        }
      ]
    })
  });
  return response.json();
};

​
Recording Usage Events

// Record usage events to the regional edge instance
const recordUsage = async (entitlementId: string, customerId: string, merchantId: string, properties: Record<string, any>) => {
  const response = await fetch('https://asia-south1-edge-api.paygentic.io/v0/usage', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      idempotencyKey: `usage-${Date.now()}-${Math.random()}`,
      entitlementId: entitlementId,
      customerId: customerId,
      merchantId: merchantId,
      timestamp: new Date().toISOString(),
      properties: properties
    })
  });
  return response.json();
};

​
Benefits of Regional Processing

  • Ultra-low latency: Process entitlements and usage events closest to your users
  • High throughput: Handle burst traffic patterns without affecting the main API

​
When to Use Edge Instances

​
✅ Use Edge API for:

  • Fetching organization data
  • Retrieving customer information
  • Reading usage metrics
  • Pulling billing history
  • Dashboard data
  • Analytics queries
  • Creating regional entitlements
  • Recording usage events for regional entitlements
  • Any GET requests

​
❌ Use Main API for:

  • Creating customers
  • Updating subscriptions
  • Creating global entitlements
  • Managing billing and invoices
  • Administrative operations

​
Best Practices

  1. Configure Regional and Global Endpoints: Set up separate base URLs for different types of operations
const API_CONFIG = {
  // For read operations and regional entitlements/usage
  regional: {
    'asia-south1': 'https://asia-south1-edge-api.paygentic.io',
    'europe-west1': 'https://europe-west1-edge-api.paygentic.io'
  },
  // For global operations (fallback)
  global: 'https://edge-api.paygentic.io',
  // For administrative operations
  admin: 'https://api.paygentic.io'
};
  1. Implement Fallback Logic: Always have a fallback to the main API for critical operations
async function fetchWithFallback(path: string) {
  try {
    const response = await fetch(`https://edge-api.paygentic.io${path}`, {
      headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
    });
    
    if (!response.ok) throw new Error('Edge request failed');
    return response;
    
  } catch (error) {
    // Fallback to main API
    return fetch(`https://api.paygentic.io${path}`, {
      headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
    });
  }
}
Edge API instances use the same authentication and rate limits as the main API. Your existing API keys will work without any changes.