Vendor Analytics

Retrieve analytics and performance metrics for a specific vendor over a given time period.

GEThttps://api.zenpayz.com/merchant/api/v1/vendors/:id/analytics

Bearer · API key

Request

Headers

Header	Description
Authorization REQUIRED	Bearer {api_key}
X-Signature REQUIRED	HMAC-SHA256 signature
X-Timestamp REQUIRED	ISO 8601 timestamp
X-Secret-Salt REQUIRED	Secret salt for HMAC validation
Content-Type REQUIRED	application/json

Path Parameters

Parameter	Type	Description
id REQUIRED	string	Vendor ID (e.g., vnd_a1b2c3d4e5f6g7h8)

Query Parameters

Parameter	Type	Description
startDate OPTIONAL	string	Start date for analytics period (ISO 8601)
endDate OPTIONAL	string	End date for analytics period (ISO 8601)
period OPTIONAL	string	Aggregation period (daily, weekly, monthly, quarterly, yearly)
environment OPTIONAL	string	Filter by environment
includeInactiveReferrals OPTIONAL	boolean	Include inactive referrals in calculations (default: false)

Response

Success (200 OK)

{
  "success": true,
  "data": {
    "vendorId": "vnd_a1b2c3d4e5f6g7h8",
    "period": {
      "startDate": "2024-01-01T00:00:00.000Z",
      "endDate": "2024-03-31T23:59:59.999Z",
      "granularity": "monthly"
    },
    "summary": {
      "totalReferrals": 45,
      "activeReferrals": 38,
      "newReferrals": 12,
      "totalTransactions": 1240,
      "totalRevenue": 620000.00,
      "totalCommission": 77500.00,
      "averageTransactionValue": 500.00,
      "conversionRate": 68.5
    },
    "timeline": [
      {
        "period": "2024-01",
        "referrals": 4,
        "transactions": 380,
        "revenue": 190000.00,
        "commission": 23750.00
      },
      {
        "period": "2024-02",
        "referrals": 3,
        "transactions": 420,
        "revenue": 210000.00,
        "commission": 26250.00
      },
      {
        "period": "2024-03",
        "referrals": 5,
        "transactions": 440,
        "revenue": 220000.00,
        "commission": 27500.00
      }
    ],
    "topReferrals": [
      {
        "referralId": "ref_e5f6g7h8i9j0k1l2",
        "merchantId": "mer_k1l2m3n4o5p6q7r8",
        "referralCode": "ACME-2024-001",
        "transactions": 85,
        "revenue": 42500.00,
        "commission": 5312.50
      },
      {
        "referralId": "ref_h8i9j0k1l2m3n4o5",
        "merchantId": "mer_l2m3n4o5p6q7r8s9",
        "referralCode": "ACME-2024-002",
        "transactions": 32,
        "revenue": 18200.00,
        "commission": 2275.00
      }
    ],
    "payoutSummary": {
      "totalPaid": 65000.00,
      "totalPending": 12500.00,
      "lastPayoutDate": "2024-03-15T14:00:00.000Z",
      "nextScheduledPayout": "2024-04-01T00:00:00.000Z"
    }
  },
  "message": "Vendor analytics retrieved successfully",
  "error": null,
  "meta": {
    "request_id": "req_xxxxx",
    "timestamp": "2024-03-21T10:30:00.000Z",
    "processing_time_ms": 320,
    "api_version": "v1",
    "endpoint": "GET /vendors/:id/analytics",
    "user_type": "merchant"
  }
}

Error Responses

Code	HTTP	Message
VALIDATION_ERROR	400	Invalid query parameters or date range
UNAUTHORIZED	401	Invalid API key
VENDOR_NOT_FOUND	404	Vendor with specified ID does not exist

Examples

cURL

curl -X GET "https://api.zenpayz.com/merchant/api/v1/vendors/vnd_a1b2c3d4e5f6g7h8/analytics?startDate=2024-01-01T00:00:00.000Z&endDate=2024-03-31T23:59:59.999Z&period=monthly" \
  -H "Authorization: Bearer zp_test_xxxxx" \
  -H "X-Timestamp: 2024-03-21T10:30:00.000Z" \
  -H "X-Signature: a1b2c3d4e5f6..." \
  -H "X-Secret-Salt: your_secret_salt" \
  -H "Content-Type: application/json"

JavaScript

const params = new URLSearchParams({
  startDate: '2024-01-01T00:00:00.000Z',
  endDate: '2024-03-31T23:59:59.999Z',
  period: 'monthly',
});

const response = await fetch(`https://api.zenpayz.com/merchant/api/v1/vendors/vnd_a1b2c3d4e5f6g7h8/analytics?${params}`, {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'X-Timestamp': timestamp,
    'X-Signature': signature,
    'X-Secret-Salt': secretSalt,
    'Content-Type': 'application/json',
  },
});

const result = await response.json();
console.log(result.data.summary.totalRevenue); // 620000.00
console.log(result.data.timeline); // Array of period data

SDK

const analytics = await zenpays.vendors.analytics('vnd_a1b2c3d4e5f6g7h8', {
  startDate: '2024-01-01T00:00:00.000Z',
  endDate: '2024-03-31T23:59:59.999Z',
  period: 'monthly',
});

console.log(analytics.summary.totalRevenue); // 620000.00
console.log(analytics.timeline); // Array of period data
console.log(analytics.payoutSummary.totalPending); // 12500.00

Related Endpoints

• Get Vendor
• Vendor Commissions
• Vendor Stats
• Vendor Payout