API Billing Service Onboarding

Automates the complete process of adding a new third-party API service to the AWS Lambda-based billing and quota monitoring system.

Purpose

This skill provides a step-by-step workflow for integrating new API services into an existing AWS monitoring infrastructure that tracks account balances, quotas, and usage across multiple third-party services. The system monitors services every 30 minutes, pushes metrics to CloudWatch, triggers alerts via SNS to Feishu, and visualizes data on a centralized dashboard.

When to Use

Use this skill when the user requests to:

• Add monitoring for a new API service's balance, quota, or credits

• Set up alerts for low balance/quota on a third-party service

• Integrate a new service into the billing dashboard

• Monitor remaining usage or spending on an external API

Common trigger phrases:

• "Add [Service] to monitoring"

• "Monitor [Service] API balance"

• "Set up quota alerts for [Service]"

• "Track [Service] credits in dashboard"

Project Context

The monitoring system is located in /path/to/monitoring-system/ and consists of:

• Runtime: Node.js 18.x (TypeScript)

• Cloud Platform: AWS Lambda + CloudWatch + Secrets Manager + EventBridge + SNS

• Commands: Managed via just (see justfile )

• Architecture: EventBridge (30min) → Lambda → CloudWatch Metrics → Alarms → SNS → Feishu

Key Files:

• adapters/*.ts

• API service adapters

• adapters/index.ts

• Adapter registry

• src/handler.ts

• Lambda entry point

• src/types.ts

• BillingMetric interface

• src/metrics.ts

• CloudWatch metric publishing

• CLAUDE.md

• Project documentation

Workflow

Step 1: Gather Service Information

Before starting implementation, collect the following information from the user:

• Service name (e.g., "resend", "sendgrid")

• API documentation URL (especially balance/quota endpoints)

• API Key/Token (will be stored in Secrets Manager)

• Alert threshold (absolute value or percentage)

• Service display name (for Dashboard labels)

Questions to ask:

• "What is the API endpoint for checking balance/quota?"

• "How does the API authenticate? (Bearer token, API key header, query param?)"

• "What response format does the API return? (JSON structure)"

• "What threshold should trigger an alert? (e.g., remaining < 100, or < 5%)"

• "What unit does the service use? (USD, credits, emails, requests?)"

Step 2: Create API Adapter

Create a new TypeScript adapter file at adapters/<service_name>.ts .

Refer to: references/adapter-templates.md for three common adapter patterns:

• Standard JSON response with balance fields

• Response headers containing quota information

• Prepaid credits with no total amount

The adapter must:

• Call the service's API to retrieve balance/quota

• Mask the API key (show first 6 and last 6 characters)

• Return a BillingMetric object with:

• service : lowercase service identifier

• apiKeyMask : masked API key

• total : total quota/balance

• remaining : remaining quota/balance

• remainingRatio : remaining/total (0-1)

• currency (optional): "USD", "CNY", etc.

• unit (optional): "credits", "emails", "requests"

Use the Read tool to examine existing adapters for reference:

• adapters/resend.ts

• Response header quota pattern

• adapters/serper.ts

• Prepaid credits pattern

• adapters/scrapedo.ts

• Standard JSON response pattern

Step 3: Register Adapter

Edit adapters/index.ts :

• Import the new adapter function

• Add entry to the adapters object

Example:

import { fetchServiceName } from "./service_name";

export const adapters = { // ... existing adapters service_name: fetchServiceName, };

Step 4: Update Lambda Handler

Edit src/handler.ts to add the service call logic.

Location: Insert before console.log("✅ Billing check completed")

Pattern:

// <Service Display Name> if (apiKeys.<service_name>) { try { console.log("🔍 Fetching <Service> quota..."); const metric = await adapters.<service_name>(apiKeys.<service_name>); await pushMetrics(metric); results.push({ service: "<service_name>", status: "success", remaining: metric.remaining, total: metric.total, ratio: metric.remainingRatio }); } catch (error: any) { console.error("❌ <Service> error:", error.message); results.push({ service: "<service_name>", status: "error", error: error.message }); } }

Step 5: Add API Key to Secrets Manager

Use the helper script to safely add the API key:

scripts/add-secret-key.sh <service_name> <api_key>

Manual alternative:

Get current secrets

aws secretsmanager get-secret-value
--secret-id api-billing-monitor/keys
--query SecretString --output text > /tmp/secrets.json

Edit /tmp/secrets.json to add: "<service_name>": "<api_key>"

Update secrets

aws secretsmanager update-secret
--secret-id api-billing-monitor/keys
--secret-string file:///tmp/secrets.json

Step 6: Build and Deploy

Quick deployment (recommended)

just deploy-quick

Or full deployment with verbose output

just deploy

Verify deployment:

Trigger Lambda manually

just invoke

Check logs for the new service

just logs | grep <service_name>

Step 7: Create CloudWatch Alarm

Choose the appropriate alarm strategy:

Strategy A: Absolute Value Threshold (for fixed quotas):

aws cloudwatch put-metric-alarm
--alarm-name "<Service>-Low-Balance"
--namespace "ThirdPartyAPIBilling"
--metric-name "Remaining"
--dimensions Name=Service,Value=<service_name>
--statistic Average
--period 1800
--evaluation-periods 1
--threshold <absolute_value>
--comparison-operator LessThanThreshold
--alarm-actions "arn:aws:sns:us-east-1:830101142436:CloudWatchAlarmsToFeishu"
--alarm-description "<Service> remaining balance below <threshold>"

Strategy B: Percentage Threshold (for variable quotas):

aws cloudwatch put-metric-alarm
--alarm-name "<Service>-Low-Ratio"
--namespace "ThirdPartyAPIBilling"
--metric-name "RemainingRatio"
--dimensions Name=Service,Value=<service_name>
--statistic Average
--period 1800
--evaluation-periods 1
--threshold 0.05
--comparison-operator LessThanThreshold
--alarm-actions "arn:aws:sns:us-east-1:830101142436:CloudWatchAlarmsToFeishu"
--alarm-description "<Service> remaining ratio below 5%"

Verify alarm creation:

just alarms | grep <Service>

Step 8: Update CloudWatch Dashboard

Use the helper script to automatically add the service to the dashboard:

scripts/add-to-dashboard.sh <service_name> "<Service Display Name>" "<masked_api_key>"

Manual alternative:

Get current dashboard configuration:

aws cloudwatch get-dashboard
--dashboard-name "API-Billing-Monitor"
--query "DashboardBody"
--output text > /tmp/dashboard.json

Edit /tmp/dashboard.json to add the service in 4 locations:

• "所有服务剩余比例趋势" metrics array

• "当前剩余比例" metrics array

• Create a new widget (optional, for detailed service chart)

• "当前剩余额度/Credits" metrics array

Update dashboard:

aws cloudwatch put-dashboard
--dashboard-name "API-Billing-Monitor"
--dashboard-body file:///tmp/dashboard.json

Refer to: references/dashboard-widget-template.json for widget JSON structure examples.

Step 9: Update Project Documentation

Edit CLAUDE.md to add the new service to the "已接入服务" table:

| <service_name> | <unit> | <threshold> | <description> |

Step 10: Verification

Run the complete verification checklist:

1. Trigger monitoring

just invoke

2. Check logs for successful execution

just logs | grep "<service_name>"

Expected: "✅ Metrics pushed for <service_name>"

3. Verify metrics in CloudWatch

aws cloudwatch list-metrics
--namespace ThirdPartyAPIBilling
--dimensions Name=Service,Value=<service_name>

4. Check alarm status

just alarms | grep "<Service>"

5. View current status

just status

6. Visit dashboard

echo "https://us-east-1.console.aws.amazon.com/cloudwatch/home?region=us-east-1#dashboards/dashboard/API-Billing-Monitor"

Success criteria:

• ✅ Lambda logs show successful metric push

• ✅ CloudWatch metrics exist for the service

• ✅ Alarm is in OK or ALARM state (not INSUFFICIENT_DATA)

• ✅ Dashboard displays the service in all charts

• ✅ Service appears in just status output

Troubleshooting

Lambda execution fails:

• Check logs: just logs

• Verify API key in Secrets Manager: just secrets-full

• Test API endpoint manually with curl/Postman

Metrics not appearing in CloudWatch:

• Confirm Lambda executed successfully: just invoke

• Check for errors in adapter code

• Verify metric push logic in logs

Dashboard shows no data:

• Wait 30 minutes for first execution cycle

• Confirm metrics exist: aws cloudwatch list-metrics --namespace ThirdPartyAPIBilling

• Verify Dashboard JSON syntax

Alarm not triggering:

• Check alarm configuration: aws cloudwatch describe-alarms --alarm-names "<Service>-Low-Balance"

• Verify metric data points exist

• Test alarm: just test-alarm <Service>-Low-Balance

Notes

• The system runs on a 30-minute schedule via EventBridge

• All API keys are stored securely in AWS Secrets Manager

• Alarms notify via SNS to Feishu webhook

• The CloudWatch namespace is ThirdPartyAPIBilling

• Common dimension: Service=<service_name> , APIKey=<masked_key>

For detailed examples and edge cases, refer to references/service-integration-examples.md .