Commerce

The commerce service synchronizes external product catalogs with AnyaSelf's internal graph. It serves as the data source when the AI agent calls the search_commerce tool, providing constrained semantic search with explainable match scoring.

Endpoints

Offer Ingestion

Method	Path	Description
`POST`	`/api/v1/households/{id}/commerce/offers`	Ingest a single normalized offer
`POST`	`/api/v1/households/{id}/commerce/offers/bulk`	Bulk ingest up to 100 offers

Ingest Offer Request:

{
  "source": "RETAILER_DIRECT",
  "url": "https://brand.com/jacket-1",
  "title": "Winter Puffer",
  "brand": "Acne Studios",
  "images": ["https://...", "https://..."],
  "price": 450,
  "currency": "USD",
  "shippingEstimate": "3-5 days",
  "availableSizes": ["S", "M", "L"],
  "colorVariants": ["Black", "Olive"],
  "returnPolicySnippet": "14 days free returns",
  "category": "OUTERWEAR",
  "occasion": ["CASUAL"],
  "season": ["WINTER"],
  "tags": ["warm", "down"]
}

Read & Browse

Method	Path	Description
`GET`	`/api/v1/households/{id}/commerce/offers`	List offers (filter: `source`, `category`, `status`)
`GET`	`/api/v1/households/{id}/commerce/offers/{offerId}`	Get offer detail

Search & Score

Method	Path	Description
`POST`	`/api/v1/households/{id}/commerce/offers/search`	Semantic search with constraints

Search Request:

{
  "constraints": {
    "category": "OUTERWEAR",
    "colors": ["Black"],
    "season": "WINTER",
    "brands": ["Acne Studios", "Toteme"],
    "maxPrice": 500,
    "sizes": ["M"],
    "keywords": ["puffer"]
  },
  "limit": 10
}

Search Response includes scored offers with explainable match features:

{
  "offers": [
    {
      "offer": { "offerId": "...", "title": "Winter Puffer", ... },
      "matchScore": 0.87,
      "features": [
        { "feature": "brand_match", "weight": 0.3, "score": 1.0, "reason": "Brand 'Acne Studios' in allowlist" },
        { "feature": "price_range", "weight": 0.2, "score": 0.9, "reason": "Price $450 within budget $500" }
      ],
      "explanations": ["Strong brand match", "Within price range"]
    }
  ],
  "total": 1,
  "constraints": { ... }
}

Lifecycle

Method	Path	Description
`PATCH`	`/api/v1/households/{id}/commerce/offers/{offerId}/status`	Update offer status (`ACTIVE`, `EXPIRED`, `UNAVAILABLE`)
`DELETE`	`/api/v1/households/{id}/commerce/offers/{offerId}`	Delete an offer

Configuration

Variable	Default	Description
`PERSISTENCE_BACKEND`	`inmemory`	`firestore` or `inmemory`
`COMMERCE_ENFORCE_DOMAIN_ALLOWLIST`	`false`	Restrict ingestion to allowed domains
`MEMBERSHIP_PROVIDER_BACKEND`	`none`	`firestore` or `none`