Sessions

The Sessions API exposes read access to journey sessions — the per-visitor or per-user run-throughs of a configured journey. A journey session captures progress (current step, step history), context data collected along the way, and — since Task #2047 — a transaction outcome (pending / success / failure) plus a human-readable outcomeReason that records the specific business event (e.g. the operationType of the committing action or the terminal step label).

Key concepts:

• status tracks the session lifecycle: active (in progress), completed (reached a terminal step), abandoned (forcibly ended), expired.

• outcome is an independent axis that records the transaction result of the journey. A completed session can still have a pending outcome if the payment is being reconciled asynchronously.

• outcomeReason provides the specific cause — useful for analytics roll-ups and admin investigations.

All endpoints require an API key with the read scope.

See also: Payments, Subscriptions.

Endpoints

GET /api/v1/sessions

List journey sessions for the tenant

get

https://peakcommerce.app/api/v1https://sandbox.peakcommerce.app/api/v1

/sessions

Authorizations

ApiKeyAuthBearerAuth

X-API-KeystringRequired

Scoped API key. Scopes: read, commerce, admin.

Query parameters

limitinteger · min: 1 · max: 100Optional

Max items to return (1–100, default 20)

Default: 20

offsetintegerOptional

Number of items to skip (default 0)

Default: 0

sortstringOptional

Field to sort by

sortDirstring · enumOptional

Sort direction

Default: ascPossible values:

statusstringOptional

Filter by status

journeyIdstringOptional

Filter to a specific journey

outcomestring · enumOptional

Filter by outcome (pending, success, failure)

Possible values:

Responses

200

Paginated list of journey sessions

400

Invalid outcome filter value

application/json

401

API key missing or invalid

application/json

get/sessions

HTTPcURLJavaScriptPython

GET /api/v1/sessions HTTP/1.1
Host: peakcommerce.app
X-API-Key: YOUR_API_KEY
Accept: */*

No content

Returns journey sessions for the calling tenant, newest first (by startedAt). Use ?outcome=success to retrieve only sessions that resulted in a purchase, or ?outcome=failure to find sessions blocked by a payment or validation error.

The response shape per session:

Field	Type	Description
id	string	UUID
journeyId	string	UUID of the parent journey
status	string	Lifecycle status
outcome	string	Transaction outcome (pending / success / failure)
outcomeReason	string | null	Human-readable cause of the resolved outcome
visitorId	string | null	Anonymous visitor identifier
userId	string | null	Authenticated user UUID
currentStepOrder	integer	Zero-based index of the current step
startedAt	string	ISO 8601 timestamp
completedAt	string | null	ISO 8601 timestamp (null if still active)
lastActivityAt	string | null	ISO 8601 timestamp

Requires the read scope.

GET /api/v1/sessions/{id}

Get a single journey session

get

https://peakcommerce.app/api/v1https://sandbox.peakcommerce.app/api/v1

/sessions/{id}

Authorizations

ApiKeyAuthBearerAuth

X-API-KeystringRequired

Scoped API key. Scopes: read, commerce, admin.

Path parameters

idstringRequired

Journey session UUID

Responses

200

Journey session details including outcome and outcomeReason

No content

404

Session not found

application/json

get/sessions/{id}

HTTPcURLJavaScriptPython

GET /api/v1/sessions/{id} HTTP/1.1
Host: peakcommerce.app
X-API-Key: YOUR_API_KEY
Accept: */*

No content

Returns the full session record including outcome and outcomeReason. Useful for post-journey reconciliation — for example, polling after a webhook to confirm whether a specific session resolved to success.

Requires the read scope. Returns 404 for any session that is not scoped to the calling tenant's API key, regardless of whether the session ID exists.