links.10x.in/docs/end-user/playbooks/ops-lab-knowledge-commerce-hub Published:

Ops Lab Playbook: Knowledge Commerce Hub

Last updated: 2026-03-08

1. Purpose and when to use this

Use this module to ingest knowledge documents, rebuild knowledge index, and validate paid-content access lifecycle with checkout and entitlement checks.

2. User roles and auth modes

  • JWT operator/creator: knowledge document management and usage reads.
  • VISITOR_COOKIE: checkout and page access-check flows.
  • NONE/public webhook consumers: settlement happens through public Stripe webhook endpoints.

3. Prerequisites checklist

  • Primer completed: Onboarding and API Primer
  • HANDLE, JWT_TOKEN configured.
  • Published paid page exists (PAGE_SLUG).
  • Visitor auth cookie available for commerce checks.

4. UI onboarding flow

  1. Open https://app.10x.in/apps/knowledge-commerce.
  2. Create a document and verify indexing state.
  3. Trigger a rebuild job.
  4. Run checkout for a paid page as visitor.
  5. Compare access check before and after successful purchase webhook processing.

5. API workflow map

  1. KC-01: POST /v2/handles/{handle}/knowledge/documents (JWT)
  2. KC-02: GET /v2/handles/{handle}/knowledge/documents (JWT)
  3. KC-03: POST /v2/handles/{handle}/knowledge/rebuild (JWT)
  4. KC-04: POST /v2/public/pages/{handle}/{pageSlug}/checkout (visitor cookie)
  5. KC-05: POST /v2/public/pages/{handle}/{pageSlug}/access-check before purchase
  6. KC-06: repeat access-check after webhook settlement
  7. KC-07: GET /v2/handles/{handle}/usage-meters (JWT)

6. cURL examples

Set module variables:

export PAGE_SLUG="premium"
export VISITOR_COOKIE="_10x_visitor=<cookie-value>"

KC-01 Create knowledge document

curl -sS -X POST "${API_BASE}/v2/handles/${HANDLE}/knowledge/documents" \
  -H "authorization: Bearer ${JWT_TOKEN}" \
  -H 'content-type: application/json' \
  -d '{
    "title":"Guide",
    "topic":"onboarding",
    "source":"manual",
    "contentType":"text/plain",
    "content":"hello world"
  }'

KC-03 Rebuild knowledge index

curl -sS -X POST "${API_BASE}/v2/handles/${HANDLE}/knowledge/rebuild" \
  -H "authorization: Bearer ${JWT_TOKEN}" \
  -H 'content-type: application/json' \
  -d '{}'

KC-04 Checkout session

curl -sS -X POST "${API_BASE}/v2/public/pages/${HANDLE}/${PAGE_SLUG}/checkout" \
  -H "cookie: ${VISITOR_COOKIE}" \
  -H 'content-type: application/json' \
  -d '{"quantity":1}'

KC-05 Access check before purchase

curl -sS -X POST "${API_BASE}/v2/public/pages/${HANDLE}/${PAGE_SLUG}/access-check" \
  -H "cookie: ${VISITOR_COOKIE}" \
  -H 'content-type: application/json' \
  -d '{}'

KC-07 Usage meter read

curl -sS "${API_BASE}/v2/handles/${HANDLE}/usage-meters" \
  -H "authorization: Bearer ${JWT_TOKEN}"

7. Expected success outputs and verification checks

  • Document create returns 201 with indexing status and documentId.
  • Rebuild request returns 202 with queued count.
  • Access-check before entitlement should return success envelope with hasAccess=false.
  • Access-check after settlement should return hasAccess=true.

8. Failure modes and remediation

  • 403 on knowledge writes:
  • Remediation: ensure operator-level role on handle.
  • Checkout succeeds but access remains false:
  • Remediation: verify Stripe webhook delivery and entitlement processing completed.
  • 401 with visitor routes:
  • Remediation: refresh visitor auth flow and update cookie value.

9. Async behavior notes

  • Document indexing and rebuild enqueue asynchronous processing tasks.
  • Checkout entitlement is completed asynchronously via webhook (WEBHOOK).
  • Usage meter reads are synchronous.

10. Related links