API usage & metering

Subby meters write requests only. Reading data is never metered. This page explains exactly what counts, what doesn't, and how to keep an eye on your usage.

The short version

• GET requests are never metered. They are still subject to rate limits.
• POST, PATCH and DELETE requests that succeed in live count as 1 write request each.
• Each plan includes a monthly allowance of write requests.
• Going over your allowance is billed, not blocked: ₦0.1 per 1,000 extra write requests, counted in blocks of 1,000.
• Nudges (SMS, WhatsApp and email reminders) are metered separately from API requests.

Monthly write allowance by plan

Full plan details are on Pricing & plans.

What counts as a write request

A request counts as 1 write request when all of these are true:

1. It was sent to the live API (https://api.mysubbyapp.com/v1).
2. Its method is POST, PATCH or DELETE.
3. It returned a 2xx status code.
4. It was not an idempotent replay of an earlier request.

Every request that meets these rules counts the same, whatever the endpoint. There are no expensive or cheap endpoints.

What never counts

Examples

How overage is calculated

At the end of each billing period:

extra_writes   = max(0, write_requests_used − included_write_requests)
billed_blocks  = round_up(extra_writes ÷ 1,000)
overage_charge = billed_blocks × overage_rate_per_1,000

Worked example on the Growth plan:

Example — Growth: 62,400 write requests − 50,000 included = 12,400 extra requests. Write overage: ₦1.24.

The overage appears as its own line on your Subby invoice, next to nudge overage.

Nudges are separate

A nudge is one reminder message delivered to one customer on one channel. Nudges have their own monthly allowance and overage rate, and they count whether Subby sends them automatically or you send them with POST /nudges.

* Enterprise nudges are unlimited up to 5,000 per month. If you regularly send more, we'll agree a custom plan with you.

Tracking your usage

In every write response

Metered requests return headers so you can track usage without extra calls:

X-Subby-Billable: true
X-Subby-Write-Usage: 48213
X-Subby-Write-Limit: 50000
X-Subby-Usage-Period-End: 2026-09-30T23:59:59Z

Usage counters update in real time. The totals on your invoice are final and are reconciled at the end of the period.

With the usage endpoint

curl "https://api.mysubbyapp.com/v1/usage" \
  -H "Authorization: Bearer $SUBBY_SECRET_KEY"

{
  "success": true,
  "data": {
    "object": "usage",
    "livemode": true,
    "plan": "growth",
    "period": { "start": "2026-09-01T00:00:00Z", "end": "2026-09-30T23:59:59Z" },
    "write_requests": {
      "used": 48213,
      "included": 50000,
      "remaining": 1787,
      "overage": 0,
      "overage_rate_per_1000": 10,
      "projected_overage_amount": 0
    },
    "read_requests": { "used": 391044, "metered": false },
    "nudges": {
      "used": 212,
      "included": 300,
      "overage": 0,
      "overage_rate": 3500,
      "overage_amount": 0
    },
    "updated_at": "2026-09-17T14:02:11Z"
  }
}

Money values in this response are in kobo, like everywhere else in the API. GET /usage is a read request, so checking it is free.

With alerts

Subby emails your account owners and sends a usage.threshold_reached webhook when you reach 80% and 100% of your write request or nudge allowance. Change the recipients in Dashboard → Developers → Usage → Alerts.

Reducing write requests

• Use idempotency keys on every POST. Safe retries after network errors don't cost anything extra.
• Don't poll with writes. Listen for webhooks and use GET to fetch details.
• Batch your setup. Create plans once and reuse them. Don't create a plan per customer.
• Let Subby run retries. Automatic retries are free. Only call POST /charges/{id}/retry when a customer asks to pay right now.