SMS Billing & Usage

WildTrack360 uses AWS SNS to send transactional SMS messages (such as Pindrop location requests). SMS is a paid add-on with per-organisation subscription tiers and monthly usage limits to control costs.

Overview

Every SMS sent through WildTrack360 is:

1. Gated against the organisation's subscription tier and monthly limit
2. Logged with full details (recipient, purpose, status, SNS message ID)
3. Counted in a monthly usage summary for billing and dashboards

If an organisation has no SMS plan or has exceeded its limit, the send is blocked and the operator sees a clear error message.

Subscription Tiers

Each organisation is assigned an SMS tier that determines how many messages they can send per month.

Tier	Monthly Limit	Intended For
NONE	0	SMS is disabled. This is the default for all organisations.
LITE	100	Small groups with occasional SMS needs
STANDARD	500	Medium organisations with regular call intake
PRO	1,500	Large organisations with high call volumes

Custom Limits

Each subscription also supports a monthlyLimit override. If set, this takes precedence over the tier default. This allows flexibility for organisations that need a non-standard quota.

Overage

By default, once an organisation hits its monthly limit, further sends are blocked. Organisations can opt in to overage by enabling the overageEnabled flag on their subscription. When overage is enabled:

• SMS messages continue to send beyond the limit
• Overage messages are tracked separately in the usage summary (overageCount)
• Overage can be billed at a per-message rate as needed

How Limits Are Enforced

Every call to the SMS service follows this flow:

1. Look up the org's SmsSubscription
   └─ No subscription or tier=NONE → BLOCKED (logged)

2. Look up the current month's SmsUsageSummary
   └─ Created automatically if it doesn't exist yet

3. Check: messageCount >= limit?
   └─ Yes + overageEnabled=false → BLOCKED (logged)
   └─ Yes + overageEnabled=true  → continue (flagged as overage)

4. Send via AWS SNS
   └─ Failure → FAILED (logged)

5. On success:
   └─ Log as SENT
   └─ Increment messageCount (and overageCount if applicable)

Every step — sent, failed, or blocked — creates an SmsLog record for auditability.

Usage Tracking

Monthly Summary

Usage is tracked per organisation, per environment (production/staging/development), per calendar month. The SmsUsageSummary record contains:

Field	Description
messageCount	Total messages attempted and sent this month
overageCount	Messages sent beyond the tier limit (only if overage is enabled)
year / month	The calendar period (e.g., 2026 / 4 for April 2026)

SMS Log

Every individual SMS attempt is recorded in the SmsLog table:

Field	Description
recipientPhone	The phone number the SMS was sent to (E.164 format)
messageBody	The content of the SMS
purpose	Why the SMS was sent (e.g., PIN_DROP_LINK)
sentById	The Clerk user ID of the operator who triggered the send
status	SENT, FAILED, or BLOCKED
snsMessageId	The AWS SNS message ID (populated on success)
createdAt	Timestamp of the attempt

Usage Warnings

The SMS service provides a getUsageWarningLevel() helper that returns a warning level based on current usage:

Threshold	Warning Level
75% of limit	75_PERCENT
90% of limit	90_PERCENT
100% of limit	LIMIT_REACHED

This can be used to show warnings in the UI or trigger notifications to administrators before the limit is hit.

Database Models

The SMS billing system adds three models to the database:

SmsSubscription

One row per organisation. Controls the tier, limit, and overage settings.

sms_subscriptions
├── organisation_id (unique)
├── tier: NONE | LITE | STANDARD | PRO
├── monthly_limit (optional override)
└── overage_enabled (default: false)

SmsUsageSummary

One row per organisation per month per environment. Tracks aggregate counts.

sms_usage_summaries
├── organisation_id + environment + year + month (unique)
├── message_count
└── overage_count

SmsLog

One row per SMS attempt. Full audit trail.

sms_logs
├── organisation_id
├── recipient_phone
├── message_body
├── purpose
├── sent_by_id
├── status: SENT | FAILED | BLOCKED
└── sns_message_id

Environment Variables

The following environment variables are required for SMS functionality:

Variable	Description
AWS_SNS_ACCESS_KEY_ID	AWS IAM access key with SNS publish permissions
AWS_SNS_SECRET_ACCESS_KEY	Corresponding secret key
AWS_SNS_REGION	AWS region for SNS (defaults to ap-southeast-2 / Sydney)
SMS_SENDER_ID	The sender ID shown on the SMS (defaults to WildTrack, max 11 characters)

Setting Up an Organisation

To enable SMS for an organisation:

1. Create an SmsSubscription record with the desired tier (e.g., LITE, STANDARD, or PRO)
2. Optionally set a custom monthlyLimit if the tier default doesn't fit
3. Optionally enable overageEnabled if the organisation wants to continue sending beyond the limit

Organisations without a subscription record (or with tier NONE) will see an error message when attempting to send SMS, prompting them to contact an administrator.

Integration with Other Modules

Module	Integration
Pindrop Location Requests	Every pindrop SMS is sent through the billing-gated SMS service with purpose PIN_DROP_LINK.
Audit Logging	SMS sends are logged in the SmsLog table. Pindrop session creation is also recorded in the main audit log.