GA4 Refund Tool - API Documentation

Complete API reference for the GA4 Refund Tool backend services

📋 Table of Contents

🌐 Base URL

http://localhost:3000/api

Production: https://refunder.analyticsbuddy.com/api

The frontend automatically detects the environment and uses the appropriate base URL.

🔒 Authentication

The API uses session-based authentication. All protected endpoints require authentication.

Login Process

  1. Send credentials to /api/auth/login
  2. Store session cookie automatically
  3. Use authenticated session for protected endpoints

Session Cookie

  • Name: connect.sid
  • Type: HttpOnly session cookie
  • Duration: 24 hours
  • Security: Secure in production (HTTPS required)

🔐 Authentication Endpoints

POST /api/auth/login

Login with username and password.

Request:

{ "username": "admin", "password": "your-password" }

Responses:

200 Success - Login successful 401 Invalid username or password
POST /api/auth/logout

Logout and destroy session.

GET /api/auth/status

Check current authentication status.

🔍 Transaction Endpoints

⚠️ All transaction endpoints require authentication.

POST /api/transactions/validate

Validate and get transaction details.

Request:

{ "transactionId": "gundog-2514001" }

Query Parameters:

  • refresh=true - Force refresh cache

Responses:

200 Valid transaction with details 400 Invalid transaction ID format 404 Transaction not found
GET /api/transactions/:transactionId

Get transaction details by ID.

Example: /api/transactions/gundog-2514001

DELETE /api/transactions/cache/:transactionId?

Clear transaction cache.

  • Clear Specific: /api/transactions/cache/gundog-2514001
  • Clear All: /api/transactions/cache

💳 Refund Endpoints

⚠️ All refund endpoints require authentication.

POST /api/refunds/process

Process a refund for a transaction.

Request (Full Refund):

{ "transactionId": "gundog-2514001", "amount": 129.99, "reason": "Customer requested refund", "refundType": "full" }

Request (Partial Refund):

{ "transactionId": "gundog-2514001", "amount": 50.00, "reason": "Partial refund - defective item", "refundType": "partial", "shipping": 9.99, "tax": 4.25, "items": [ { "itemId": "SKU123", "itemName": "Refunded Product", "quantity": 1, "price": 50.00 } ] }

Responses:

200 Refund processed successfully 400 Missing transaction ID or amount 404 Transaction not found 409 Refund already processed
GET /api/refunds/status/:transactionId

Check if refund exists for transaction.

Example: /api/refunds/status/gundog-2514001

GET /api/refunds/history

Get refund history (Phase 2 feature).

⚙️ Admin Endpoints

⚠️ All admin endpoints require authentication.

GET /api/admin/status

Get overall system status including GCS and database health.

GET /api/admin/health/gcs

Check GCS integration health.

200 GCS connection healthy 503 Unable to connect to GCS
POST /api/admin/transactions/refresh

Smart refresh - checks for new data and imports if needed.

DELETE /api/admin/transactions/clear

Clear all master transactions (admin only).

❌ Error Responses

Common Status Codes

Code Description
400Bad Request (missing/invalid parameters)
401Unauthorized (authentication required)
404Not Found (resource doesn't exist)
409Conflict (duplicate operation)
500Internal Server Error
503Service Unavailable

Error Response Format

{ "error": "Error description", "message": "Detailed error message", "timestamp": "2024-01-15T16:00:00Z" }

🏷️ Transaction ID Format

  • Pattern: gundog-XXXXXX (where X is a number)
  • Examples: gundog-2514001, gundog-2513999
  • Valid Range: gundog-2513930 to gundog-2514264 (for mock data)

🔧 Environment Configuration

Required Environment Variables

# Session security SESSION_SECRET=your-session-secret-here # GA4 Configuration GA4_MEASUREMENT_ID=G-XXXXXXXXXX GA4_API_SECRET=your-api-secret-here GA4_PROPERTY_ID=309409373 # GCS Integration (optional) GCS_BUCKET_NAME=your-bucket-name GCS_AUTO_REFRESH=true # Server Configuration PORT=3000

📖 Usage Examples

Complete Authentication Flow

// 1. Login const loginResponse = await fetch('/api/auth/login', { method: 'POST', headers: { 'Content-Type': 'application/json' }, credentials: 'include', body: JSON.stringify({ username: 'admin', password: 'your-password' }) }); // 2. Use authenticated endpoints const transactionResponse = await fetch('/api/transactions/validate', { method: 'POST', headers: { 'Content-Type': 'application/json' }, credentials: 'include', // Include session cookie body: JSON.stringify({ transactionId: 'gundog-2514001' }) }); // 3. Process refund const refundResponse = await fetch('/api/refunds/process', { method: 'POST', headers: { 'Content-Type': 'application/json' }, credentials: 'include', body: JSON.stringify({ transactionId: 'gundog-2514001', amount: 129.99, reason: 'Customer requested refund', refundType: 'full' }) });

cURL Examples

Development Environment:

# Login curl -X POST http://localhost:3000/api/auth/login \ -H "Content-Type: application/json" \ -d '{"username": "admin", "password": "your-password"}' \ -c cookies.txt # Validate Transaction curl -X POST http://localhost:3000/api/transactions/validate \ -H "Content-Type: application/json" \ -b cookies.txt \ -d '{"transactionId": "gundog-2514001"}'

Production Environment:

# Login curl -X POST https://refunder.analyticsbuddy.com/api/auth/login \ -H "Content-Type: application/json" \ -d '{"username": "admin", "password": "your-password"}' \ -c cookies.txt # Process Refund curl -X POST https://refunder.analyticsbuddy.com/api/refunds/process \ -H "Content-Type: application/json" \ -b cookies.txt \ -d '{ "transactionId": "gundog-2514001", "amount": 129.99, "reason": "Customer requested refund", "refundType": "full" }'