Vendor Commissions

Retrieve a paginated list of commission records for a specific vendor, with filtering and sorting support.

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

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
status OPTIONAL	string	Filter by commission status (pending, calculated, paid, cancelled, disputed)
commissionType OPTIONAL	string	Filter by commission type (percentage, fixed, tiered)
calculatedAfter OPTIONAL	string	Commissions calculated after this date (ISO 8601)
calculatedBefore OPTIONAL	string	Commissions calculated before this date (ISO 8601)
paidAfter OPTIONAL	string	Commissions paid after this date (ISO 8601)
paidBefore OPTIONAL	string	Commissions paid before this date (ISO 8601)
minCommissionAmount OPTIONAL	number	Minimum commission amount
currency OPTIONAL	string	Filter by currency code (e.g., USD, EUR)
environment OPTIONAL	string	Filter by environment
page OPTIONAL	number	Page number (default: 1)
limit OPTIONAL	number	Results per page (default: 20)
sortBy OPTIONAL	string	Field to sort by
sortOrder OPTIONAL	string	Sort direction (asc, desc)

Response

Success (200 OK)

{
  "success": true,
  "data": [
    {
      "commissionId": "comm_d4e5f6g7h8i9j0k1",
      "vendorId": "vnd_a1b2c3d4e5f6g7h8",
      "referralId": "ref_e5f6g7h8i9j0k1l2",
      "transactionId": "txn_f6g7h8i9j0k1l2m3",
      "amount": 125.00,
      "currency": "USD",
      "commissionRate": 12.5,
      "commissionType": "percentage",
      "baseAmount": 1000.00,
      "status": "paid",
      "calculatedAt": "2024-03-15T10:00:00.000Z",
      "paidAt": "2024-03-20T14:00:00.000Z",
      "environment": "production"
    },
    {
      "commissionId": "comm_g7h8i9j0k1l2m3n4",
      "vendorId": "vnd_a1b2c3d4e5f6g7h8",
      "referralId": "ref_h8i9j0k1l2m3n4o5",
      "transactionId": "txn_i9j0k1l2m3n4o5p6",
      "amount": 75.50,
      "currency": "USD",
      "commissionRate": 12.5,
      "commissionType": "percentage",
      "baseAmount": 604.00,
      "status": "pending",
      "calculatedAt": "2024-03-21T08:00:00.000Z",
      "paidAt": null,
      "environment": "production"
    }
  ],
  "message": "Vendor commissions retrieved successfully",
  "error": null,
  "meta": {
    "request_id": "req_xxxxx",
    "timestamp": "2024-03-21T10:30:00.000Z",
    "processing_time_ms": 95,
    "api_version": "v1",
    "endpoint": "GET /vendors/:id/commissions",
    "user_type": "merchant",
    "pagination": {
      "page": 1,
      "limit": 20,
      "totalItems": 2,
      "totalPages": 1
    }
  }
}

Error Responses

Code	HTTP	Message
VALIDATION_ERROR	400	Invalid query parameters
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/commissions?status=pending&currency=USD&page=1&limit=20" \
  -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({
  status: 'pending',
  currency: 'USD',
  page: '1',
  limit: '20',
});

const response = await fetch(`https://api.zenpayz.com/merchant/api/v1/vendors/vnd_a1b2c3d4e5f6g7h8/commissions?${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); // Array of commission records
console.log(result.meta.pagination.totalItems); // Total count

SDK

const commissions = await zenpays.vendors.listCommissions('vnd_a1b2c3d4e5f6g7h8', {
  status: 'pending',
  currency: 'USD',
  page: 1,
  limit: 20,
});

console.log(commissions.data); // Array of commission records
console.log(commissions.meta.pagination.totalItems); // Total count

Related Endpoints

• Get Vendor
• Vendor Referrals
• Vendor Payout
• Vendor Analytics