UC-016 — Monitor Credit and Subscription

Field	Value
ID	UC-016
Goal	Check subscription and remaining credit
Channel	All
Complexity	Basic
Estimated time	5 minutes
APIs involved	GET /api/partner-gateway/v1/subscription, GET /api/partner-gateway/v1/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 the available credit drops below a threshold, preventing service interruptions.

Monitoring flow

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

Prerequisites

• API Key that includes the SUBSCRIPTION operation (see UC-014)
• Active subscription on the Qlara platform

Step 1 — Check the subscription status

Retrieve the active plan, its status and the current billing period.

curl -X GET https://api.qlara.ai/api/partner-gateway/v1/subscription \
  -H "X-Api-Key: YOUR_API_KEY"

Response — Active subscription

{
  "planCode": "annual_business",
  "status": "active",
  "billingPeriodStart": "2026-10-02T16:12:17+02:00",
  "billingPeriodEnd": "2027-10-02T01:59:59+02:00",
  "nextRenew": "2026-11-01T23:00:00Z",
  "canceled": false,
  "nextPlan": null
}

Reading the response

billingPeriodStart and billingPeriodEnd delimit the current billing period. On an annual plan, nextRenew is the next monthly reset of the usage counters, so it falls well before billingPeriodEnd. When canceled is true and status is still active, the plan stays usable until billingPeriodEnd and is not renewed; nextPlan names the plan that takes over at that point, or is null when none is scheduled.

Behind the scenes — How billing works

1. Plan: Each account has one active plan, identified by planCode.
2. Renewal: The plan renews at the end of each billing period, unless it has been canceled.
3. Plan changes: A change scheduled for the next renewal sets nextPlan and marks the current plan as canceled, which stays usable until the end of its period.
4. Credit: Credit is deducted with each sent message. The cost varies by channel and destination. Credit reserved for operations still in progress, such as a scheduled campaign, is counted in frozenCredit until they complete.

Step 2 — Check remaining credit

Verify how much credit is available for sending messages.

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

Response — Available credit

{
  "credit": 50000,
  "frozenCredit": 5000,
  "availableCredit": 45000
}

All three values are in credits: availableCredit is what you can spend right now, credit minus frozenCredit, the part reserved for operations still in progress.

Set up automatic alerts

Configure a periodic job that queries this endpoint and sends a notification when availableCredit drops below a critical threshold to avoid service interruptions.

Expected result

Step	Action	Result
1	GET /subscription	Plan code, status, billing period
2	GET /subscription/credit	Total, frozen and available credit

Complete end-to-end example

Scenario TechStore: monitoring script with alerts.

# 1. Verify active subscription
echo "=== Subscription Status ==="
curl -s -X GET https://api.qlara.ai/api/partner-gateway/v1/subscription \
  -H "X-Api-Key: YOUR_API_KEY" | jq '{planCode, status, billingPeriodEnd, canceled}'

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

echo "Available credit: $AVAILABLE"

# 3. Alert if credit is low (threshold in credits)
THRESHOLD=10000
if [ "$AVAILABLE" -lt "$THRESHOLD" ]; then
  echo "WARNING: Credit below critical threshold!"
fi

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 — Invalid API key or operation not enabled

{
  "error": "Invalid API Key"
}

Solution: Verify that the X-Api-Key header is present and valid, and that the key includes the SUBSCRIPTION operation: the API answers 401 with the same body in both cases. To check the operations of a key, see UC-014.

Next steps

• UC-014 — API Key Management: Manage access keys for your account
• UC-006 — Bulk SMS Campaign: Plan campaigns based on available credit

References

• API Reference — Subscription