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
| Region | Endpoint |
|---|
| Global (Auto-routing) | https://edge-api.paygentic.io |
| Asia South | https://asia-south1-edge-api.paygentic.io |
| Europe West | https://europe-west1-edge-api.paygentic.io |
Using Edge Instances
Global Edge (Recommended)
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"
# 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
- 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'
};
- 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.
