Skip to main content
POST

Authorizations

Authorization
string
header
required

Use a Bouclay secret key (sk_test_..., sk_live_...) or restricted key (rk_test_..., rk_live_...).

A secret key can call every endpoint. A restricted key can only call the endpoints its scopes cover. A scope is {resource}:{access}, for example customers:read or refunds:write, and write includes read. GET requests need read access and everything else needs write, except POST /subscriptions/{id}/items/{item}/preview, which only needs subscriptions:read. A request outside the key's scopes gets 403 permission_denied naming the missing scope, and its Idempotency-Key is not used up.

Publishable keys (pk_...) are rejected by server-side API endpoints. A key's mode scopes what it can see and charge: a test key can never reach a live card.

Headers

Idempotency-Key
string
required

Required for POST and PATCH requests. Replays identical method + path + body requests and rejects mismatched re-use.

Required string length: 1 - 255

Body

application/json
name
string
required
Maximum string length: 255
eventName
string
required

Unique per business.

Maximum string length: 100
Pattern: ^[A-Za-z0-9][A-Za-z0-9._:-]*$
aggregation
enum<string>
required
  • count: the number of events.
  • sum: the sum of each event's value.
  • max: the largest value in the window.
  • last: the value of the latest event.
  • unique_count: the number of distinct values of properties.{uniqueKey}.
Available options:
count,
sum,
max,
last,
unique_count
valueKey
string | null

For sum, max, and last, the property holding the number. Omit to read the event's value.

uniqueKey
string | null

Required for unique_count.

unitLabel
string | null
Maximum string length: 50

Response

Meter response.

data
object
required
meta
object
required