Upsert Faq

PUT/v1/stores/{store_id}/knowledge/faqs/{external_ref}Scope knowledge:write

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

Upsert by `external_ref`: `200` updated, `201` created (the handler sets the status).

Parameters

Parameters of Upsert Faq
Name	In	Type	Description
store_idrequired	path	string
external_refrequired	path	string	Merchant FAQ key

Request body (FaqUpsert)

Request body of Upsert Faq
Field	Type	Description
answerrequired	string	1–10000 characters
locale	string	2–35 characters · pattern `^[A-Za-z]{2,3}(-[A-Za-z0-9]{2,8})*$`
questionrequired	string	1–500 characters

Example request

curl -X PUT "https://api.shopassist.coec.dk/v1/stores/sto_01j8000000e008000000000000/knowledge/faqs/string" \
  -H "Authorization: Bearer $SHOPASSIST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"answer":"string","locale":"da-DK","question":"string"}'

Response 200 (KnowledgeDocument)

Response of Upsert Faq
Field	Type	Description
chunk_countrequired	integer
content_previewrequired	string
doc_typerequired	string (enum)	one of policy, page, faq, file, blog, size_chart, other
fetched_atrequired	string \| null	format date-time
idrequired	string	pattern `^kdoc_[0-9a-hjkmnp-tv-z]{26}$`
injection_flagsrequired	InjectionFlag[]
injection_flags[].excerptrequired	string
injection_flags[].rulerequired	string
localerequired	string \| null
pending_changerequired	PendingChange \| null
pending_change.diff_previewrequired	string
pending_change.reasonrequired	"off_domain" \| "crawled_policy" \| "content_changed" \| "mass_change"
pending_change.sincerequired	string	format date-time
policy_typerequired	string (enum) \| null	one of refund, return, shipping, privacy, terms, contact, legal_notice, subscription, withdrawal, other
review_statusrequired	"approved" \| "pending_review" \| "rejected"
source_idrequired	string	pattern `^ksrc_[0-9a-hjkmnp-tv-z]{26}$`
statusrequired	"active" \| "excluded" \| "error"
titlerequired	string
updated_atrequired	string	format date-time
urlrequired	string \| null	format uri · ≤ 2048 characters

{
  "chunk_count": 1,
  "content_preview": "string",
  "doc_type": "policy",
  "fetched_at": "2026-09-28T10:15:30.123Z",
  "id": "kdoc_01j8000000e008000000000000",
  "injection_flags": [
    {
      "excerpt": "string",
      "rule": "string"
    }
  ],
  "locale": "da-DK",
  "pending_change": {
    "diff_preview": "string",
    "reason": "off_domain",
    "since": "2026-09-28T10:15:30.123Z"
  },
  "policy_type": "refund",
  "review_status": "approved",
  "source_id": "ksrc_01j8000000e008000000000000",
  "status": "active",
  "title": "string",
  "updated_at": "2026-09-28T10:15:30.123Z",
  "url": "https://shop.example/products/linen-shirt"
}

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