Skip to main content

ADR-0012 — Twilio for SMS

  • Status: Accepted
  • Date: 2026-04-28
  • Decision-makers: Tom Anderson

Context​

The Helm Service Tickets slice (and later Marketing slice) needs outbound SMS for:

  • "Your bike is ready" notifications
  • Appointment reminders
  • Trade-in offers
  • Marketing opt-in confirmations

Two-way conversational SMS is on the roadmap; v0.1 is one-way only.

Alternatives:

  • Twilio — incumbent, full Canadian number support, mature API, A2P 10DLC handled, sub-accounts for multi-tenant cost attribution
  • Bandwidth.com — cheaper US rates but limited Canadian-number support
  • MessageBird — strong European presence, weaker Canadian pricing
  • Plivo — competitive pricing, smaller ecosystem
  • Per-shop Twilio accounts — each shop has their own Twilio account; eliminates Kvick from the middle but creates ops burden

Constraints:

  • Canadian phone numbers (most shops are in BC; numbers should look local to the customer)
  • Per-shop cost attribution (each shop pays for what they send)
  • Low ops burden on Kvick

Decision​

Use Twilio with one Kvick-owned account and per-shop sub-accounts:

  • One master Twilio account (Kvick's)
  • Each shop's deployment uses a Twilio sub-account (created at onboarding)
  • Each shop owns one or more Twilio phone numbers attached to their sub-account
  • Helm sends SMS via fetch() to https://api.twilio.com/2010-04-01/Accounts/{sub}/Messages.json using the sub-account's auth
  • Twilio's monthly invoice goes to Kvick; we re-bill each shop based on their sub-account's usage
  • A2P 10DLC registration (US numbers) handled at the master-account level; Canadian numbers don't require it

Two-way SMS, when added, will use Twilio's webhooks (POST /api/webhooks/twilio/{shop}) and the same sub-account model.

Consequences​

Positive:

  • Twilio's reliability and Canadian number availability beats alternatives
  • Sub-accounts give us clean per-shop cost attribution without N separate vendor relationships
  • A2P 10DLC and compliance is centralized at the master account level
  • Mature webhook + idempotency story
  • Twilio's deliverability across carriers is the best in class

Negative:

  • Twilio rates are higher than some competitors
  • Kvick fronts the SMS spend and re-bills shops — small cash flow friction
  • A vendor outage at Twilio affects every shop's SMS — but we deliberately fail-quietly (fail-quietly-recover-loudly) so the rest of the flow continues

Mitigations:

  • The shop owner's monthly bill from Helm includes SMS pass-through with a small markup; cash flow nets out
  • The SMS adapter (src/lib/twilio.js) is the swap point if we ever consolidate to a cheaper vendor

Notes​

For transactional email (receipts, owner digests), see future ADR on email provider — current preference Resend or Postmark; not chosen yet.

See also​