Headless CartPrep

The headless-cartprep service isolates the fragile logic of automating third-party e-commerce carts from the core Orchestrator. When the AI agent decides to build a cart, it dispatches a job here for asynchronous browser-based automation.

Endpoints

Method	Path	Description
`POST`	`/api/v1/households/{id}/cartprep/jobs`	Create a new cart prep job
`GET`	`/api/v1/households/{id}/cartprep/jobs/{jobId}`	Poll job state + result
`POST`	`/api/v1/households/{id}/cartprep/jobs/{jobId}/process`	Trigger async processing

Create Job

{
  "offerUrl": "https://brand.com/jacket-1",
  "size": "M",
  "color": "Black",
  "quantity": 1,
  "shippingPrefs": "standard",
  "sessionId": "ses_99xyz",
  "purchaseRequestId": "req_123",
  "purchaseIntentId": "pi_456"
}

Job Response

{
  "jobId": "cp_abc123",
  "householdId": "h1",
  "requestedByUserId": "usr_1",
  "purchaseRequestId": "req_123",
  "purchaseIntentId": "pi_456",
  "state": "CART_READY",
  "offerUrl": "https://brand.com/jacket-1",
  "size": "M",
  "color": "Black",
  "quantity": 1,
  "cartUrl": "https://brand.com/cart?session=xyz",
  "recording": [...],
  "summary": { "itemsAdded": 1, "total": "$450.00" },
  "errorCode": null,
  "errorMessage": null,
  "createdAt": "2026-03-08T10:00:00+00:00",
  "updatedAt": "2026-03-08T10:00:12+00:00"
}

Job Lifecycle

See Data Models → CartPrep Job Lifecycle for the state diagram and full error code table.

Runner Backends

Backend	Description
`simulated`	Immediate fake success — no browser launched (default for local dev)
`playwright`	Real Chromium instance via Playwright, physically manipulating the DOM

Configuration

Variable	Default	Description
`CARTPREP_RUNNER_BACKEND`	`simulated`	`simulated` or `playwright`
`CARTPREP_ENFORCE_DOMAIN_ALLOWLIST`	`false`	Restrict automation to allowed domains
`PERSISTENCE_BACKEND`	`inmemory`	`firestore` or `inmemory`
`ARTIFACTS_AUDIT_BASE_URL`	`http://artifacts-audit:8007/api/v1`	Audit service URL
`ARTIFACTS_AUDIT_ENABLED`	`true`	Enable recording persistence
`ARTIFACTS_AUDIT_REQUIRED`	`false`	Fail if audit service unreachable