Send a usage event

curl --request POST \
  --url https://bouclay.com/api/v1/meter-events \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "eventName": "api.request",
  "customer": "ctm_123",
  "identifier": "req_01J8ZQ",
  "timestamp": "2026-10-14T09:31:00Z",
  "properties": {
    "endpoint": "/v1/charges"
  }
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    eventName: 'api.request',
    customer: 'ctm_123',
    identifier: 'req_01J8ZQ',
    timestamp: '2026-10-14T09:31:00Z',
    properties: {endpoint: '/v1/charges'}
  })
};

fetch('https://bouclay.com/api/v1/meter-events', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://bouclay.com/api/v1/meter-events"

payload = {
    "eventName": "api.request",
    "customer": "ctm_123",
    "identifier": "req_01J8ZQ",
    "timestamp": "2026-10-14T09:31:00Z",
    "properties": { "endpoint": "/v1/charges" }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://bouclay.com/api/v1/meter-events",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'eventName' => 'api.request',
    'customer' => 'ctm_123',
    'identifier' => 'req_01J8ZQ',
    'timestamp' => '2026-10-14T09:31:00Z',
    'properties' => [
        'endpoint' => '/v1/charges'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

{
  "data": {
    "identifier": "req_01J8ZQ",
    "eventName": "api.request",
    "meter": "mtr_123",
    "customer": "ctm_123",
    "timestamp": "2023-11-07T05:31:56Z",
    "value": 1,
    "properties": {},
    "status": "active",
    "cancelledAt": "2023-11-07T05:31:56Z",
    "createdAt": "2023-11-07T05:31:56Z"
  },
  "meta": {
    "requestId": "req_550e8400-e29b-41d4-a716-446655440000"
  }
}

{
  "data": {
    "identifier": "req_01J8ZQ",
    "eventName": "api.request",
    "meter": "mtr_123",
    "customer": "ctm_123",
    "timestamp": "2023-11-07T05:31:56Z",
    "value": 1,
    "properties": {},
    "status": "active",
    "cancelledAt": "2023-11-07T05:31:56Z",
    "createdAt": "2023-11-07T05:31:56Z"
  },
  "meta": {
    "requestId": "req_550e8400-e29b-41d4-a716-446655440000"
  }
}

{
  "error": {
    "type": "request_error",
    "code": "authentication_failed",
    "detail": "<string>",
    "errors": [
      {
        "field": "<string>",
        "message": "<string>"
      }
    ]
  },
  "meta": {
    "requestId": "req_550e8400-e29b-41d4-a716-446655440000"
  }
}

Usage

Send a usage event

Early access. Not yet turned on for every account: until it is, this answers 404 not_found. Build against it now and ask us to turn it on.

Record one usage fact. Events are stored as sent and aggregated only when read, so a total is always recomputable from its events.

No Idempotency-Key is needed. The event’s own identifier dedupes: resending one returns 200 with the stored original, unchanged, whatever the resend carried. A new event returns 201.

Refusals are 422 with one of these codes: meter_not_found, meter_archived, customer_not_found, timestamp_in_future (more than 5 minutes ahead), missing_property (a unique_count meter’s property is absent), invalid_value (a value that isn’t a whole number from 0 to 1,000,000,000,000), usage_period_closed (the timestamp falls in a period that has already been invoiced), subscription_paused (the subscription that bills this meter was paused at the timestamp), or invalid_field.

POST

meter-events

Send a usage event

curl --request POST \
  --url https://bouclay.com/api/v1/meter-events \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "eventName": "api.request",
  "customer": "ctm_123",
  "identifier": "req_01J8ZQ",
  "timestamp": "2026-10-14T09:31:00Z",
  "properties": {
    "endpoint": "/v1/charges"
  }
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    eventName: 'api.request',
    customer: 'ctm_123',
    identifier: 'req_01J8ZQ',
    timestamp: '2026-10-14T09:31:00Z',
    properties: {endpoint: '/v1/charges'}
  })
};

fetch('https://bouclay.com/api/v1/meter-events', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://bouclay.com/api/v1/meter-events"

payload = {
    "eventName": "api.request",
    "customer": "ctm_123",
    "identifier": "req_01J8ZQ",
    "timestamp": "2026-10-14T09:31:00Z",
    "properties": { "endpoint": "/v1/charges" }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://bouclay.com/api/v1/meter-events",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'eventName' => 'api.request',
    'customer' => 'ctm_123',
    'identifier' => 'req_01J8ZQ',
    'timestamp' => '2026-10-14T09:31:00Z',
    'properties' => [
        'endpoint' => '/v1/charges'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

{
  "data": {
    "identifier": "req_01J8ZQ",
    "eventName": "api.request",
    "meter": "mtr_123",
    "customer": "ctm_123",
    "timestamp": "2023-11-07T05:31:56Z",
    "value": 1,
    "properties": {},
    "status": "active",
    "cancelledAt": "2023-11-07T05:31:56Z",
    "createdAt": "2023-11-07T05:31:56Z"
  },
  "meta": {
    "requestId": "req_550e8400-e29b-41d4-a716-446655440000"
  }
}

{
  "data": {
    "identifier": "req_01J8ZQ",
    "eventName": "api.request",
    "meter": "mtr_123",
    "customer": "ctm_123",
    "timestamp": "2023-11-07T05:31:56Z",
    "value": 1,
    "properties": {},
    "status": "active",
    "cancelledAt": "2023-11-07T05:31:56Z",
    "createdAt": "2023-11-07T05:31:56Z"
  },
  "meta": {
    "requestId": "req_550e8400-e29b-41d4-a716-446655440000"
  }
}

{
  "error": {
    "type": "request_error",
    "code": "authentication_failed",
    "detail": "<string>",
    "errors": [
      {
        "field": "<string>",
        "message": "<string>"
      }
    ]
  },
  "meta": {
    "requestId": "req_550e8400-e29b-41d4-a716-446655440000"
  }
}

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.

Resource	Endpoints	Access
`customers`	customers, their addresses and payment methods	read, write
`entitlements`	`/customers/{id}/entitlements`	read
`credits`	`/customers/{id}/credit-balance`, credit purchases, credit grants, auto-reloads, credit holds (committing one records its usage)	read, write
`catalog`	products, plans, prices	read, write
`meters`	meters	read, write
`usage`	meter events, `/customers/{id}/usage`	read, write
`discounts`	discounts	read
`subscriptions`	subscriptions	read, write
`invoices`	invoices	read, write
`credit_notes`	credit notes, `POST /invoices/{id}/credit-notes` (a refund to the card also needs `refunds:write`)	read, write
`payments`	payments	read
`refunds`	refunds, `POST /payments/{id}/refunds`, chargebacks and their outcome	read, write
`checkout_sessions`	checkout sessions	read, write
`portal_sessions`	portal sessions	write
`events`	events	read
`webhook_endpoints`	webhook endpoints	read, write
`metrics`	metrics	read

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.

Body

application/json

eventName

string

required

The meter's event name. event_name is accepted too.

Example:

"api.request"

customer

string

required

A Bouclay customer ID, or the externalRef you gave the customer.

Example:

"ctm_123"

identifier

string

required

Your unique ID for this event. Resending it is safe.

Maximum string length: 255

Example:

"req_01J8ZQ"

timestamp

string<date-time>

When it happened. Defaults to now; at most 5 minutes in the future.

value

integer

default:1

The amount, for sum, max, and last meters that read value. Whole numbers only; pick a unit that makes it one. A meter with a valueKey reads that property instead, under the same bounds.

Required range: 0 <= x <= 1000000000000

properties

object | null

Response

Meter event response. 201 when stored, 200 when the identifier was already stored.

data

object

required

Show child attributes

Overview

Customers

Customer addresses

Entitlements

Credits

Usage

Payment methods

Catalog

Meters

Discounts

Subscriptions

Metrics

Invoices

Credit notes

Payments

Refunds

Chargebacks

Events

Checkout sessions

Portal sessions

Payment links

Webhook endpoints

Send a usage event

Authorizations

Body

Response