New Billing Report API: Reconcile SMS Spend by rateCode

If you send SMS on behalf of your own customers — as a reseller, an agency, or a platform with multiple brands or cost centres — you've probably built a spreadsheet to answer one question at the end of every month: who do I bill for what? As of today the WebSMS Connexus API answers it for you.

The idea is simple: pass a rateCode with each send — your customer number, an account code, anything up to 95 characters — and WebSMS records it against the actual billed transaction. At the end of the month, one call to the new billing report endpoint returns a line per rateCode with message counts, segment counts and the exact amounts you were charged. Because the report is built from the same transactions that debit your account, it always reconciles with your WebSMS balance — multi-part messages, GST and all.

Step 1: Tag your sends

Add rateCode to any send request. It doesn't change routing or delivery — it's purely a billing tag:

Shell

curl -X POST https://api.websms.co.nz/api/connexus/sms/out \
  -H "Authorization: Bearer wst_your_token..." \
  -d "to=6421234567" \
  -d "body=Your order has shipped" \
  -d "messageClass=transactional" \
  -d "rateCode=CUST-0042"

The same parameter works on the OTP and appointment reminder endpoints. Because those send types are billed at their own rates, they report under suffixed codes — CUST-0042-OTP and CUST-0042-APPT — so each of your customers can have up to three cleanly separated lines: standard SMS, OTP, and appointment traffic.

Step 2: Pull the month's report

At the end of the month, one call:

Shell

curl -X POST https://api.websms.co.nz/api/connexus/billing/query \
  -H "Authorization: Bearer wst_your_token..." \
  -d "month=2026-08"

…returns one row per rateCode:

JSON

{
  "status": "success",
  "rateCodes": [
    {
      "rateCode": "CUST-0042",
      "sendType": "sms",
      "messages": 1250,
      "segments": 1311,
      "amount": 91.77,
      "gst": 13.7655,
      "totalInclGst": 105.5355
    },
    {
      "rateCode": "CUST-0042-OTP",
      "sendType": "otp",
      "baseRateCode": "CUST-0042",
      "messages": 340,
      "segments": 340,
      "amount": 27.20,
      "gst": 4.08,
      "totalInclGst": 31.28
    },
    {
      "rateCode": "untagged",
      "sendType": "sms",
      "messages": 18,
      "segments": 18,
      "amount": 1.26,
      "gst": 0.189,
      "totalInclGst": 1.449
    }
  ],
  "totals": { "messages": 1608, "segments": 1669, "amount": 120.23, "gst": 18.0345, "totalInclGst": 138.2645 }
}

Every row carries a derived sendType (sms, otp or appointment) and, on suffixed rows, a baseRateCode — so your invoicing script can group per customer without parsing strings. Messages sent without a tag are collected under untagged, so nothing ever disappears from the totals.

A month-end reconciliation workflow

Summary per customer

Call /billing/query?month=2026-08. Group rows by baseRateCode (or rateCode where no suffix) and you have each customer's message count, segment count and your cost — ready to apply your own margin.

Drill into disputes

Add rateCode=CUST-0042 to report a single customer — a base code automatically includes its -OTP and -APPT lines. Add detail=1 for the individual transactions behind the totals.

Cross-check delivery

The delivery status query now returns each message's rateCode too, so per-message delivery evidence lines up with the billing bucket it was charged to.

Good to know

Amounts are NZD exclusive of GST, with GST reported separately (zero for non-NZ accounts). totalInclGst saves you the addition.
The report covers billed transactions from August 2026 onwards — older sends predate the per-transaction tagging and won't appear.
Reports can span any date range up to a year (start_date/end_date), not just calendar months.
rateCodes are free-form — if you already send one for shortcode routing, it's now doing double duty as your billing tag with no changes needed.

Start tagging today

Add rateCode to your sends now and your first month-end report builds itself.

Billing report docs Connexus API reference

Reconcile SMS Spend by Customer: the New Billing Report API