Skip to content

Record usage of a metered feature for a customer

POST
/v1/usage
curl --request POST \
--url https://api.seal0.app/v1/usage \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{ "customer_id": "example", "feature_key": "example", "quantity": 1 }'

Adds quantity to the customer’s usage in the period containing the server’s current time: the subscription’s billing period, otherwise the UTC calendar month. Exact: each request is one write. Retry with the same Idempotency-Key to avoid counting twice.

Idempotency-Key
string
>= 1 characters <= 255 characters

Optional; replays the stored response for 24 hours.

Media typeapplication/json
object
customer_id
required

Opaque customer ID from the integrating application.

string
/^[A-Za-z0-9._:-]{1,255}$/
feature_key
required

Feature or plan key.

string
/^[a-z][a-z0-9_]{0,63}$/
quantity

Units to add to the current period’s usage.

integer format: int64
default: 1 >= 1 <= 9007199254740991

The usage after recording.

Media typeapplication/json

The Customer’s usage of the feature after recording, in the current period.

object
customer_id
required

Opaque customer ID from the integrating application.

string
/^[A-Za-z0-9._:-]{1,255}$/
feature_key
required

Feature or plan key.

string
/^[a-z][a-z0-9_]{0,63}$/
period_end
required
string format: date-time
period_start
required
string format: date-time
used
required
integer format: int64

Example generated

{
"customer_id": "example",
"feature_key": "example",
"period_end": "2026-04-15T12:00:00Z",
"period_start": "2026-04-15T12:00:00Z",
"used": 1
}

Error envelope.

Media typeapplication/json
object
error
required
object
code
required

Stable snake_case error code.

string
field
required

Offending input field, when known.

string
nullable
message
required
string
request_id
required
string

Example generated

{
"error": {
"code": "example",
"field": "example",
"message": "example",
"request_id": "example"
}
}

Error envelope.

Media typeapplication/json
object
error
required
object
code
required

Stable snake_case error code.

string
field
required

Offending input field, when known.

string
nullable
message
required
string
request_id
required
string

Example generated

{
"error": {
"code": "example",
"field": "example",
"message": "example",
"request_id": "example"
}
}

Error envelope.

Media typeapplication/json
object
error
required
object
code
required

Stable snake_case error code.

string
field
required

Offending input field, when known.

string
nullable
message
required
string
request_id
required
string

Example generated

{
"error": {
"code": "example",
"field": "example",
"message": "example",
"request_id": "example"
}
}

Error envelope.

Media typeapplication/json
object
error
required
object
code
required

Stable snake_case error code.

string
field
required

Offending input field, when known.

string
nullable
message
required
string
request_id
required
string

Example generated

{
"error": {
"code": "example",
"field": "example",
"message": "example",
"request_id": "example"
}
}

Error envelope.

Media typeapplication/json
object
error
required
object
code
required

Stable snake_case error code.

string
field
required

Offending input field, when known.

string
nullable
message
required
string
request_id
required
string

Example generated

{
"error": {
"code": "example",
"field": "example",
"message": "example",
"request_id": "example"
}
}

Error envelope.

Media typeapplication/json
object
error
required
object
code
required

Stable snake_case error code.

string
field
required

Offending input field, when known.

string
nullable
message
required
string
request_id
required
string

Example generated

{
"error": {
"code": "example",
"field": "example",
"message": "example",
"request_id": "example"
}
}