Record usage

Usage endpoint

How the platform records counted estimates on Stripe's meter, and what every error means.

Record counted estimates

The platform calls this to tell Stripe's meter how many estimates were counted for a customer. Recording usage never charges anyone: Stripe drafts the invoice at the end of the period, and a person sends it.

Fields

Field	Type	Rules
`stripeCustomerId`	string	Required. Starts with cus_.
`quantity`	integer	Optional, defaults to 1. From 1 to 1000.
`occurredAt`	ISO 8601 date-time with offset	Optional. Within the last 35 days and no more than 5 minutes ahead.
`identifier`	string	Optional, up to 200 characters. An idempotency key, like the platform's estimate event id. Stripe drops repeats for 24 hours.

Example request

bash

curl -X POST https://xtimates.com/api/estimates/usage \
  -H "Authorization: Bearer $PLATFORM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "stripeCustomerId": "cus_123",
    "quantity": 1,
    "occurredAt": "2026-10-20T14:05:00-04:00",
    "identifier": "estimate_evt_8841"
  }'

Response

A good call answers with the meter event Stripe recorded:

json

{ "ok": true, "id": "<meter event id>", "eventName": "<meter event name>", "quantity": 1 }

Errors

Every error answers with a JSON body that says what went wrong in plain words: { "error": "…" }.

Status	Means
`400`	The body isn't JSON, or a field breaks a rule. The message names the field.
`401`	The bearer key is missing or wrong.
`429`	Too many requests. The body carries retryAfterSeconds; wait that long and retry.
`503`	The endpoint isn't configured on this deployment yet.
`500`	Something broke on our side. Retry later with the same identifier.

Using these means you agree to the Developer Terms. Questions: support@xtimates.com.