Hermos API
Concepts

Customer evidence

Record activity and support communications, and read activity metadata.

The API reference generates a page for each of these operations:

OperationRequired scopeAuthentication
POST /v1/customers/{id}/activity (recordCustomerActivity)customer_activity:writeSecret or restricted API key only.
GET /v1/customers/{id}/activity (listCustomerActivity)customers:readAuthorized bearer credential or company member session.
POST /v1/customers/{id}/communications (recordCustomerCommunication)customer_communications:writeAuthorized 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.

On this page