Count signups safely with atomic increments

Avoid lost updates when workers increment the same insight card, and learn why atomic arithmetic doesn't solve duplicate delivery or reconciliation.

7 min read
Two blue arrows beside a yellow counter and a coral plus sign.

Two people sign up at the same time. Both workers read 100, both add one, and both save 101. Your counter looks reasonable, but one signup has disappeared.

An atomic increment fixes that particular problem. It doesn't fix duplicate deliveries, a lost response, or an event that your application never sends. This guide shows where the boundary sits, using Butters insight cards and a signup counter. If you're deciding which numbers belong on a card, start with Metrics that are just a number .

Choose the question before the operation

There are two different questions hiding behind a number called Signups.

One is "How many users does our database contain right now?" The other is "How many signup events have we counted?" They might agree today and drift apart tomorrow. Deleted accounts, imported accounts, test users, duplicate deliveries, and failed requests all affect that comparison.

If your database can cheaply answer the first question, read that total and set the card. If you want a running total updated as events happen, increment it. Name the card so the person reading it knows which meaning you chose.

For this example, Signup events counts accepted signup notifications. It isn't a billing ledger or your source of truth for account ownership.

Set a starting value

Open API in Butters and get a secret API key. Keep it in your server environment as BUTTERS_API_KEY, with the project ID in BUTTERS_PROJECT_ID. Publishable browser keys can't update insights.

To create or replace a card, send a POST:

curl --fail-with-body -X POST https://app.getbutters.com/api/insight \
  -H "Authorization: Bearer $BUTTERS_API_KEY" \
  -H "Content-Type: application/json" \
  --data "$(jq -n \
    --arg project "$BUTTERS_PROJECT_ID" \
    '{project: $project, title: "Signup events", value: 100, icon: "📈"}')"

That sets the value to 100. It doesn't add 100 to an existing card. Run it again and the card still reads 100, regardless of its previous value.

POST also accepts display strings, which is useful for a value such as $1,200. A card you intend to increment needs a numeric value. Formatting the currency into the stored value prevents arithmetic later.

Cards are identified by project and title. Use the same title in later requests. Signup events and Signups are different cards, even if you intended one to be a renamed version of the other.

Add the change, not your guessed total

Send a PATCH with $inc to add one:

curl --fail-with-body -X PATCH https://app.getbutters.com/api/insight \
  -H "Authorization: Bearer $BUTTERS_API_KEY" \
  -H "Content-Type: application/json" \
  --data "$(jq -n \
    --arg project "$BUTTERS_PROJECT_ID" \
    '{project: $project, title: "Signup events", "$inc": 1}')"

The addition happens in the database update. Two successful concurrent increments add two, without each caller having to read the card first. If the card doesn't exist, the increment becomes its initial value.

The API accepts negative numbers, zero, and decimals. Send a JSON number such as 1, not the string "1". The amount must be finite. A successful request returns 200 with {"ok":true}.

For a refund total you might subtract. For queue depth you might add when work is enqueued and subtract when it's removed. Before using the same approach for money, define the units and rounding in your application. Integer minor units are easier to reason about than a mixture of formatted strings and floating-point amounts.

Use it from server JavaScript

You don't need a new dependency for the HTTP request. This helper works in a server runtime with native fetch:

export async function incrementSignupEvents() {
  const response = await fetch('https://app.getbutters.com/api/insight', {
    method: 'PATCH',
    headers: {
      Authorization: `Bearer ${process.env.BUTTERS_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      project: process.env.BUTTERS_PROJECT_ID,
      title: 'Signup events',
      $inc: 1,
    }),
    signal: AbortSignal.timeout(10_000),
    redirect: 'error',
  })

  if (!response.ok) {
    throw new Error(`Insight update failed (${response.status}): ${await response.text()}`)
  }
  return response.json()
}

The example sets a ten-second client timeout and refuses redirects. It doesn't retry. Call it after your application accepts the signup, and await it before a short-lived serverless handler ends.

The pushed Butters server SDK has an equivalent incrementInsight('Signup events', 1) method. The server SDK guide explains its installation and errors. At the time this draft was checked, npm 0.1.0 didn't include the server entry point, so the fetch example works independently of that release.

Atomic doesn't mean counted once

Imagine this sequence: Butters receives the increment, the database adds one, and the connection drops before your server receives the success response.

Your server sees an error. The card has already changed. If you resend the request, it changes again.

That is different from the lost-update problem we started with. Atomic arithmetic prevents concurrent callers from overwriting one another's additions. It doesn't identify two requests as attempts to report the same business event.

The increment endpoint doesn't accept an idempotency key. Putting an event ID in your own log helps you investigate, but it doesn't make the API deduplicate requests. Don't add an automatic retry loop and describe the result as exactly-once counting.

A rate-limit response that rejects a request is different from a network timeout with an unknown outcome. Your application should keep enough information to distinguish a rejected update from one whose result you couldn't observe.

Keep your business record first

A signup should succeed because your application committed the user record, not because an external counter updated successfully.

If you save the user and then the insight request fails, the user still exists. If you send the increment first and the signup transaction rolls back, your card reports something that never happened. Neither ordering gives you a transaction spanning your database and Butters.

For important reporting, store the signup and an outbound reporting record together in your own transaction. A worker can send those records afterward. That's the outbox pattern: it makes pending work visible and recoverable in your application.

An outbox alone still doesn't give this increment endpoint exactly-once delivery. A worker can lose the response after a successful send. Keep the original business data so you can reconcile the displayed total, and choose a delivery strategy appropriate to the accuracy you need.

For an operational card, occasional reconciliation may be sufficient. For a financial balance, keep the authoritative ledger in your own system and publish a derived display value.

Reconcile without undoing new work

Suppose a scheduled job computes a total of 500. While that query runs, an incoming request increments the card to 501. The scheduled job then POSTs 500 and overwrites the newer value.

Each request worked correctly. Your application mixed an absolute snapshot with incremental updates without coordinating their boundaries.

Pick one writer strategy for a card. You can refresh an authoritative total periodically using POST. Or you can maintain increments and reconcile during a coordinated pause or with a defined cutoff and tracked changes. Don't let an old snapshot race with new deltas and assume the database will infer your intent.

Also decide whether a decrement means an event was reversed or simply that your current population became smaller. A count of signup events usually doesn't decrease when an account is deleted. A count of active accounts does. Those deserve different names.

Test concurrency and failure separately

Use a disposable project or a clearly named test card. Set its value to zero, send twenty increments concurrently, and reload Insights. After twenty successful requests, the expected value is twenty.

Then test a negative increment. Finally, set the value to a display string and try to increment it. You should get 400 with Insight value must be numeric to increment. Use POST to restore a numeric value before continuing.

Check these tests without adding blind retries. If a request fails, record its outcome and investigate it. Otherwise the retry policy becomes part of the test without you noticing.

The insight documentation lists the request fields and error responses. A wrong key returns 401, a publishable key is refused, and a project your key can't access returns 404.

Use increments when you know the change. Use replacement values when you know the total. Keep the original business records, because a convenient counter is only useful when you know what it counts.