UC-016 — Monitor Credit and Subscription

Field	Value
ID	UC-016
Goal	Check subscription, remaining credit and contact quota
Channel	All
Complexity	Basic
Estimated time	5 minutes
APIs involved	GET /api/v1/partner-gateway/subscription, GET /api/v1/partner-gateway/subscription/contacts, GET /api/v1/partner-gateway/subscription/credit

Real-world scenarios

• Billing dashboard: The CFO of MarketingPro integrates subscription data into the internal dashboard to monitor monthly messaging costs.
• Low credit alert: TechStore's system sends an automatic Slack alert when credit drops below 50 EUR, preventing service interruptions.
• Check contact quota: Before importing 10,000 new contacts, the team verifies that the current plan has sufficient capacity.

Monitoring flow

The diagram shows the three main queries to get a complete overview of your account status.

Prerequisites

• Active API Key with billing read permissions
• Active subscription on the Qlara platform

Step 1 — Check the subscription status

Retrieve the details of the active plan and expiration date.

curl -X GET https://lora-api.agiletelecom.com/api/v1/partner-gateway/subscription \
  -H "X-Api-Key: YOUR_API_KEY"

Response — Active subscription

{
  "subscriptionId": "sub_abc123def456",
  "plan": "Business Pro",
  "status": "ACTIVE",
  "startDate": "2026-01-01T00:00:00+01:00",
  "endDate": "2026-12-31T23:59:59+01:00",
  "autoRenew": true,
  "features": {
    "sms": true,
    "rcs": true,
    "whatsapp": true,
    "maxContacts": 50000,
    "webhooks": true
  }
}

:::info Plan and features The features field indicates which channels and features are included in your plan. If a channel is false, API calls for that channel will return 403 Forbidden. :::

Behind the scenes — How billing works

1. Plan: Each account has an associated plan that defines enabled channels, maximum number of contacts and monthly credit included.
2. Renewal: If autoRenew is true, the plan renews automatically at expiration. In case of failed payment, the account goes to SUSPENDED status after a 7-day grace period.
3. Upgrade/Downgrade: Plan changes are immediate for upgrades, applied at the next billing cycle for downgrades.
4. Credit: Credit is deducted with each sent message. The cost varies by channel and destination.

Step 2 — Check remaining credit

Verify how much credit is available for sending messages.

curl -X GET https://lora-api.agiletelecom.com/api/v1/partner-gateway/subscription/credit \
  -H "X-Api-Key: YOUR_API_KEY"

Response — Available credit

{
  "balance": 1250.75,
  "currency": "EUR",
  "lastRechargeDate": "2026-04-01T00:00:00+02:00",
  "lastRechargeAmount": 500.00,
  "estimatedMessagesRemaining": {
    "sms": 35735,
    "rcs": 25015,
    "whatsapp": 17867
  }
}

:::warning Set up automatic alerts Configure a periodic job that queries this endpoint and sends a notification when balance drops below a critical threshold to avoid service interruptions. :::

Step 3 — Check the contact quota

Check how many contacts you have used against your plan limit.

curl -X GET https://lora-api.agiletelecom.com/api/v1/partner-gateway/subscription/contacts \
  -H "X-Api-Key: YOUR_API_KEY"

Response — Contact quota

{
  "used": 32450,
  "total": 50000,
  "percentage": 64.9,
  "lists": 12
}

Behind the scenes — Contact quota calculation

1. Counting: Each unique contact (by phone number) is counted only once, even if present in multiple lists.
2. Deduplication: The system automatically deduplicates contacts with the same normalized number (e.g. +39347... and 0347... are the same contact).
3. Thresholds: When reaching 80% of the quota, the platform sends a warning email. At 100%, imports are blocked but sending to existing contacts remains active.

Expected result

Step	Action	Result
1	GET /subscription	Active plan, enabled channels, expiry date
2	GET /subscription/credit	Balance in EUR, estimated remaining messages
3	GET /subscription/contacts	Contacts used vs. total available

Complete end-to-end example

Scenario TechStore: monitoring script with alerts.

# 1. Verify active subscription
echo "=== Subscription Status ==="
curl -s -X GET https://lora-api.agiletelecom.com/api/v1/partner-gateway/subscription \
  -H "X-Api-Key: YOUR_API_KEY" | jq '{plan: .plan, status: .status, endDate: .endDate}'

# 2. Check remaining credit
echo "=== Remaining Credit ==="
BALANCE=$(curl -s -X GET https://lora-api.agiletelecom.com/api/v1/partner-gateway/subscription/credit \
  -H "X-Api-Key: YOUR_API_KEY" | jq -r '.balance')

echo "Balance: EUR $BALANCE"

# 3. Alert if credit is low
if (( $(echo "$BALANCE < 50" | bc -l) )); then
  echo "WARNING: Credit below critical threshold!"
fi

# 4. Check contact quota
echo "=== Contact Quota ==="
curl -s -X GET https://lora-api.agiletelecom.com/api/v1/partner-gateway/subscription/contacts \
  -H "X-Api-Key: YOUR_API_KEY" | jq '{used: .used, total: .total, percentage: .percentage}'

Variants

Scheduled monitoring with cron

Integrate the script into a cron job for automatic daily checks:

# crontab -e
# Every day at 8:00 AM - check credit
0 8 * * * /opt/scripts/check-credit.sh >> /var/log/credit-monitor.log 2>&1

Common errors

401 Unauthorized — Missing API Key

{
  "status": "fail",
  "data": {
    "authentication": "Invalid or missing API key"
  }
}

Solution: Verify that the X-Api-Key header is present and valid.

403 Forbidden — Billing permissions not enabled

{
  "status": "fail",
  "data": {
    "authorization": "API key does not have billing read permissions"
  }
}

Solution: Your API Key must have billing read permissions. Contact the admin to enable them or create a new key with the correct permissions.

Next steps

• UC-014 — API Key Management: Manage access keys for your account
• UC-007 — Manage Contacts and Lists: Organize contacts before checking quota
• UC-006 — Bulk SMS Campaign: Plan campaigns based on available credit

References

• API Reference — Subscription