123eworld Knowledge Hub → Transactional SMS → Page 175
Transactional SMS API Billing Architecture: Segments, Provider Attempts, Pricing Rules, Credits and Reconciliation
A practical architecture guide for SMS billing, segment-based charging, provider attempts, pricing revisions, credits, invoices and reconciliation.
Why billing needs its own architecture
SMS billing can depend on message segments, destination, provider route, service tier, credits, taxes or contractual pricing. Billing should therefore consume durable messaging events rather than trying to infer charges from API requests alone.
Logical message versus attempt
A customer sends one logical message, but the platform may make several provider attempts. The billing rule must specify whether charges occur on acceptance, provider submission, segment count, delivery or another defined event.
Segment calculation
If billing is segment-based, preserve the encoding and segment calculation used at send time. Recalculating later from the current encoding library can create discrepancies after rule changes.
Pricing revisions
Pricing changes should be versioned. Every billable event should retain the pricing revision used to calculate its amount.
Credits
Credit-based accounts need atomic balance operations. Two concurrent workers must not both believe the same balance is available.
Reservations
For high-value or prepaid accounts, the platform may reserve credit before provider submission and settle or release it later. The reservation lifecycle must be recoverable after worker failure.
Retries and failover
Retries should not automatically create multiple customer charges unless the commercial contract says each provider attempt is billable. Billing identity must remain separate from technical attempt identity.
Refunds and adjustments
Failed or disputed operations may require adjustments. Keep adjustment records rather than editing historical invoices invisibly.
Reconciliation
Compare billing records with message state, segment counts, provider evidence and account ledger. Reconciliation should be repeatable and idempotent.
Invoice generation
Invoices should be generated from immutable or controlled billing events. Store enough detail to explain totals without exposing unnecessary message content.
Testing
Test concurrent credit use, pricing changes, long messages, retries, refunds, provider failover and duplicate events.
Production checklist
Define billable event, segment rules, pricing revision, credits, reservations, retries, adjustments, reconciliation and invoice evidence.
Developer takeaway
Billing should be a durable consequence of messaging events. Separate commercial identity from technical attempts so retries and provider changes do not corrupt customer charges.
Implementation architecture
Implement billing from an immutable event or ledger model. When a message becomes billable, create a billing event containing tenant, logical message, segment count, pricing revision, amount and source event. Credit reservations should use atomic ledger operations. Reconciliation should compare billing events with messaging evidence and generate adjustments rather than rewriting historical charges.
Production checklist
Production check: run concurrent charges, pricing changes, long messages, retries, credits, refunds and reconciliation without creating duplicate charges.
Billing event identity
Every charge should have a unique billing-event ID and reference the logical message ID. A retry of the same technical operation must not create a second billing event unless the commercial rule explicitly says so.
Pricing hierarchy
Pricing can depend on tenant plan, destination, sender type, route, segment count or negotiated rates. Resolve these rules through a deterministic pricing engine and retain the rule revision used.
Credit ledger
A ledger is safer than simply storing a mutable balance. Credits added, reserved, consumed, released and adjusted can then be reconstructed and audited.
Concurrent charging
Two workers can finish simultaneously. Credit reservation and consumption must be atomic so the account cannot spend the same balance twice.
Refunds
Refunds should create new ledger entries or adjustments rather than modifying the original charge. This preserves an immutable financial history.
Provider evidence
Provider attempts can be linked to billing events without making provider-specific IDs the customer-facing billing identity.
Reconciliation
Run scheduled reconciliation between message records, segment calculations, provider evidence and billing ledger. Differences should become explicit exceptions for investigation.
Invoice detail
Customers need enough information to understand charges: date, logical message reference, destination category, segment count, rate revision and amount where appropriate. Avoid exposing sensitive message content.
Final rule
Billing is a financial ledger built on messaging events. Make every charge traceable, versioned and reversible through explicit adjustments.
Pricing engine
Keep pricing logic separate from message submission. The pricing engine should accept normalized message attributes and return a rate and calculation revision. This separation allows pricing changes without modifying the transport pipeline.
Segment evidence
Store the encoding type, segment count and calculation revision when the message becomes billable. If a customer disputes a charge months later, the platform should be able to reproduce the calculation.
Credit reservation
A reservation can move through reserved, consumed, released or expired states. Each transition should be idempotent so worker retries do not double-consume credit.
Pricing changes
A new price should apply according to an explicit effective time. Messages accepted before the change but processed later need a documented rule rather than an accidental one.
Reconciliation jobs
Billing reconciliation should compare counts and amounts by tenant, date, route and pricing revision. Exceptions should be stored as cases rather than silently corrected.
Invoice audit
An invoice total should be traceable to ledger events. Do not require support staff to inspect individual SMS content to explain a total.
Closing guidance
The billing layer should make commercial outcomes as traceable as message delivery outcomes. Durable evidence is the foundation of customer trust.
Tax and fees
If taxes, platform fees or minimum charges apply, represent them as separate billing components rather than hiding them inside the SMS rate. This makes invoices easier to explain and pricing changes easier to audit.
Usage aggregation
Aggregate billing events only after individual events are durable. An aggregate total should never be the only financial record because it makes reconciliation difficult when one item changes.
Credit expiry
If credits expire, record the expiry policy and ledger event explicitly. Do not simply reduce a mutable balance without an audit trail.
Operational conclusion
A reliable SMS billing system combines an immutable event trail, deterministic pricing and an auditable account ledger.
Billing dispute handling
When a customer disputes a charge, support should be able to trace the amount to a billing event, message ID, segment calculation and pricing revision. The workflow should not require editing the original charge.
Ledger recovery
The ledger should be reconstructable from durable events and should support consistency checks after database recovery or migration.
Final implementation principle
A billing system earns trust when every amount can be explained from immutable evidence.
Reference scenario
A 160-character message is billed as two segments under the active encoding rules. The platform stores the segment count, pricing revision and amount in a billing event. A provider retry does not create another charge. Later reconciliation compares the event with message and provider evidence.
Reference scenario conclusion
Billing becomes explainable because the financial event is tied to durable messaging evidence.
Final engineering test
For billing, the final engineering test should process concurrent messages against a limited credit balance and force worker retries. The ledger must never consume the same credit twice, and the final amount must reconcile with message segment evidence and the active pricing revision. Then create an adjustment and confirm that the original charge remains immutable.
Documentation reference
Billing documentation should explain whether provider failover creates a new billable event, a new attempt under one charge or another commercial outcome. This rule should be stable and visible because technical retry behaviour can otherwise produce unexpected invoice disputes.
Advanced reference
A billing system should distinguish usage measurement from commercial calculation. Usage measurement records what happened: message identity, segment count, destination class and provider evidence. Commercial calculation determines what that usage costs under a pricing revision. Keeping the two layers separate makes pricing changes, negotiated discounts and invoice adjustments easier to manage. It also allows the platform to correct a measurement error without hiding the correction inside a manually edited invoice. This separation is one of the strongest foundations for a trustworthy messaging billing system.
Final reference note
Keep usage events and pricing revisions immutable once invoiced, with corrections represented as explicit adjustments.
Completion rule
Financial corrections should be additive ledger events.
Final quality rule
Reconcile invoices against durable usage events.
Continue through the 123eworld Knowledge Hub
Explore the complete 123eworld Knowledge Hub for practical SMS API, transactional messaging and developer architecture guides.
Visit 123eworld.com for messaging and digital communication services.