Billing Integration Guide
Integrate Semaswift billing for subscriptions, payments, and usage tracking.
Subscription Management
List Available Plans
GET /api/v1/billing/plans
{
"plans": [
{
"id": "plan_starter",
"name": "Starter",
"price": 49.00,
"currency": "USD",
"interval": "month",
"features": {
"users": 5,
"storage_gb": 10,
"voice_minutes": 500
}
}
]
}
Create Subscription
POST /api/v1/billing/subscriptions
Content-Type: application/json
Authorization: Bearer YOUR_TOKEN
{
"plan_id": "plan_professional",
"payment_method_id": "pm_card_xxx"
}
Update Subscription
PATCH /api/v1/billing/subscriptions/{subscription_id}
{
"plan_id": "plan_enterprise"
}
Payment Methods
Add Payment Method
POST /api/v1/billing/payment-methods
Content-Type: application/json
Authorization: Bearer YOUR_TOKEN
{
"type": "card",
"token": "tok_visa_xxx"
}
Set Default Payment Method
POST /api/v1/billing/payment-methods/{pm_id}/default
Invoices
List Invoices
GET /api/v1/billing/invoices
Download Invoice PDF
GET /api/v1/billing/invoices/{invoice_id}/pdf
Usage Tracking
Current Usage
GET /api/v1/billing/usage
{
"period_start": "2024-01-01",
"period_end": "2024-01-31",
"users": {
"limit": 50,
"used": 35
},
"storage": {
"limit_gb": 100,
"used_gb": 45.7
},
"voice_minutes": {
"limit": 5000,
"used": 2340
}
}
Usage History
GET /api/v1/billing/usage/history?period=6m
Wallet & Credits
Check Balance
GET /api/v1/billing/wallet
{
"balance": 250.00,
"currency": "USD",
"auto_recharge": {
"enabled": true,
"threshold": 50.00,
"amount": 100.00
}
}
Add Credits
POST /api/v1/billing/wallet/top-up
{
"amount": 100.00,
"payment_method_id": "pm_card_xxx"
}
Webhooks
Subscribe to billing events:
| Event | Description |
|---|---|
subscription.created | New subscription |
subscription.updated | Plan changed |
subscription.canceled | Subscription ended |
invoice.paid | Payment successful |
invoice.failed | Payment failed |
usage.threshold | Usage limit approaching |
Best Practices
- Monitor usage - Set up alerts before limits
- Handle payment failures - Retry with backoff
- Test in sandbox - Use test cards
- Keep payment methods updated - Prevent service interruption