Customer evidence
Record activity and support communications, and read activity metadata.
The API reference generates a page for each of these operations:
| Operation | Required scope | Authentication |
|---|---|---|
POST /v1/customers/{id}/activity (recordCustomerActivity) | customer_activity:write | Secret or restricted API key only. |
GET /v1/customers/{id}/activity (listCustomerActivity) | customers:read | Authorized bearer credential or company member session. |
POST /v1/customers/{id}/communications (recordCustomerCommunication) | customer_communications:write | Authorized bearer credential or company member session. |
Product-restricted members cannot list activity or record communications. This
restriction is checked again for requests using a previously successful idempotency key.
All three routes accept an optional Idempotency-Key.
A buyer's active free ($0 recurring, without a trial) plan ends automatically when
the buyer buys a paid recurring price for that product through checkout, even if
the new paid price starts with a trial. A plan the seller manages directly in
Stripe is never ended.
Hermos matches only the checkout's bound customer ID or the merchant's
subject_ref, never a typed email address. Without either identity binding,
an anonymous buyer on another device keeps the free plan alongside the paid one.
Buying another free price or a one-time price does not end an existing free plan.
If journal admission refuses the cleanup, checkout still completes and the free
plan stays active.
Record activity
Send an events array containing 1–100 entries. Each entry needs type,
occurred_at (an RFC 3339 timestamp), and a stable identifier of 1–255 characters.
Types are login, access, download, license_activated, and usage.
Login and access events need ip or device_id. Optional fields include
user_agent, product, entitlement, subject_ref, and detail.
Detail must be a flat string-valued object whose canonical JSON is at most
2,048 UTF-8 bytes. IP addresses must be valid IPv4 or IPv6 addresses without zone IDs.
{
"events": [{
"type": "access",
"occurred_at": "2026-10-13T12:00:00Z",
"identifier": "course-access-123",
"device_id": "merchant-device-123",
"detail": { "lesson": "introduction" }
}]
}The batch is atomic. Reusing an identifier for the same customer returns the
existing event with duplicate: true; it does not overwrite the original or
consume the daily cap. An identifier already assigned to another customer returns
identifier_conflict. The intake limit is 600 requests per minute per principal,
plus 5,000 new events per customer per UTC day.
Entitlements must belong to the customer or its access customer. If both product and entitlement are supplied, their products must match. Entitlement first/last access timestamps update only when the occurrence lies within a recorded base-item access window.
Read activity
The GET operation returns paginated metadata, newest first: type, occurred_at,
source, and ip_country. Raw IP addresses, device identifiers, user agents, and
activity detail are omitted. Use the standard list query parameters and cursor.
Record communications
Send kind (refund_request or support_message), direction (inbound or
outbound), channel (email, chat, phone, helpdesk, or other), occurred_at,
identifier, and body. Optional fields are subject, external_ref, payment,
and subscription. The subject limit is 998 Unicode code points; the body limit
is 65,536 UTF-8 bytes. Linked payments and subscriptions must belong to the customer.
Identifiers deduplicate within the company and mode; another customer's identifier
returns a conflict. Responses contain metadata without the subject or body.
Both intake operations accept occurrences from the previous 400 days through five minutes in the future, measured against the database receipt clock. Deleted or erasure-fenced customers cannot receive new evidence. See Errors for specific detail rules and Rate limits for retry headers.