List Handoffs

GET/v1/stores/{store_id}/handoffsScope conversations:read

Scope: conversations:read (scopes and plan access)
Rate limit: 600 requests/min per API key (test keys: 60/min) (rate limits)

`Page<HandoffAdmin & { conversation_id }>` (newest first).

Parameters

Parameters of List Handoffs
Name	In	Type	Description
store_idrequired	path	string
limit	query	integer	Page size
cursor	query	string \| null	Cursor from the previous page

Example request

curl -X GET "https://api.shopassist.coec.dk/v1/stores/sto_01j8000000e008000000000000/handoffs" \
  -H "Authorization: Bearer $SHOPASSIST_API_KEY"

Response 200 (Page_HandoffAdminListItem_)

Response of List Handoffs
Field	Type	Description
datarequired	HandoffAdminListItem[]
data[].accepted_atrequired	string \| null	format date-time
data[].agentrequired	AgentRef \| null
data[].agent.display_namerequired	string
data[].conversation_idrequired	string	pattern `^conv_[0-9a-hjkmnp-tv-z]{26}$`
data[].delivered_atrequired	string \| null	format date-time
data[].expected_wait_secondsrequired	integer \| null
data[].idrequired	string	pattern `^hof_[0-9a-hjkmnp-tv-z]{26}$`
data[].messagerequired	string	Localized shopper-facing status text
data[].reasonrequired	string (enum)	one of shopper_request, ai_escalation, action_request, policy, repeated_failure, error, outside_hours, quota_block, limit_reached
data[].requested_atrequired	string	format date-time
data[].requested_byrequired	"shopper" \| "ai" \| "agent" \| "system"
data[].shopperrequired	HandoffShopper	`HandoffAdmin.shopper` (`platform_customer_id` only for `identity_level = customer`).
data[].shopper.emailrequired	string \| null
data[].shopper.email_verifiedrequired	boolean
data[].shopper.identity_levelrequired	"guest" \| "order_lookup" \| "order_otp" \| "customer"
data[].shopper.namerequired	string \| null
data[].shopper.platform_customer_idrequired	string \| null
data[].staterequired	"requested" \| "waiting_for_agent" \| "live" \| "delivered_offline" \| "failed" \| "resolved"
data[].statusrequired	string (enum)	one of requested, waiting_for_agent, live, delivering, delivered, failed, resolved, cancelled
data[].summaryrequired	string \| null
data[].targetrequired	"live_chat" \| "email" \| "helpdesk" \| null
data[].targetsrequired	HandoffTargetView[]
data[].targets[].external_urlrequired	string \| null	format uri · ≤ 2048 characters
data[].targets[].integration_idrequired	string \| null	pattern `^int_[0-9a-hjkmnp-tv-z]{26}$`
data[].targets[].last_errorrequired	string \| null
data[].targets[].statusrequired	"pending" \| "delivered" \| "failed" \| "skipped"
data[].targets[].typerequired	string
has_morerequired	boolean
next_cursorrequired	string \| null	Opaque cursor for the next page; null on the last page

{
  "data": [
    {
      "expected_wait_seconds": 120,
      "id": "hof_01j8000000e008000000000001",
      "message": "We've let the team know. Someone will be with you shortly.",
      "state": "waiting_for_agent",
      "target": "live_chat"
    }
  ],
  "has_more": true,
  "next_cursor": "string"
}

Errors

Every error uses the error envelope; the code field is stable.

400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
422 Unprocessable Content
429 Too Many Requests