This service persists recommendations in a database and tracks their lifecycle state. Every recommendation generated by any domain (discounts, shipping, etc.) MUST be persisted here before being presented to the merchant.
Service: wix.ecom.agentic.recommendations.v1.AgenticRecommendationsService
Base URL: https://manage.wix.com/_api/agentic-recommendations/v1/agentic-recommendations
Use CallWixSiteAPI to invoke each endpoint:
Important: You must have a siteId before calling any of these. Use ListWixSites first to resolve the site.
| Field | Type | Access | Description |
|---|---|---|---|
id | string (GUID) | readOnly | Auto-generated unique identifier |
revision | int64 | readOnly | Optimistic lock — must match current value for state transitions |
createdDate | Timestamp | readOnly | When the recommendation was created |
updatedDate | Timestamp | readOnly | When the recommendation was last updated |
title | string | writable | Short human-readable title (max 200 chars) |
reasoning | string | writable | Why this recommendation is being made, citing specific data (max 2000 chars) |
domain | string | writable | Business domain: "shipping", "discounts", etc. (max 50 chars) |
urgency | enum | writable | CRITICAL, HIGH, MEDIUM, or LOW |
advice | Advice | writable | The action to take (see below) |
state | enum | readOnly | Current lifecycle state (see State Machine) |
expiresAt | Timestamp | writable | When the recommendation auto-expires |
conversationId | string (GUID) | writable | Links all recommendations in a session |
decidedBy | string | readOnly | Who made the last state transition |
rejectionReason | string | readOnly | Reason for rejection (max 1000 chars) |
rejectionPermanent | boolean | readOnly | If true, this action type is permanently blocked for this site |
executionResult | ExecutionResult | readOnly | Result of execution (set on DONE/FAILED) |
| Field | Type | Description |
|---|---|---|
action | string | Action identifier (e.g., "apply_discount", "create_shipping_option") (max 100 chars) |
params | object | Domain-specific parameters (discount config, shipping option details, etc.) |
successCriteria | string | How to verify the action succeeded (max 500 chars) |
| Field | Type | Description |
|---|---|---|
status | enum | SUCCESS, PARTIAL_FAILURE, or FAILURE |
summary | string | Description of what happened (max 2000 chars) |
error | string | Error message if failed (max 2000 chars) |
resultPayload | object | Additional result data |
| From | To | Trigger | API Method |
|---|---|---|---|
| — | PROPOSED | Recommendation created | BatchCreate / Create |
| PROPOSED | APPROVED | Merchant approves | Approve |
| PROPOSED | REJECTED | Merchant rejects | Reject |
| PROPOSED | EXPIRED | expiresAt passed | Automatic (scheduler) |
| PROPOSED | PROPOSED | Merchant modifies parameters | Update (state unchanged) |
| APPROVED | EXECUTING | Execution begins | MarkExecuting |
| EXECUTING | DONE | Execution succeeded | MarkDone |
| EXECUTING | FAILED | Execution failed | MarkFailed |
Creates multiple recommendations (1-100) atomically. All start in PROPOSED state. Use this as the default — always batch recommendations together.
Endpoint: POST https://manage.wix.com/_api/agentic-recommendations/v1/agentic-recommendations/batch-create
Request:
Response:
Important: Save the id and revision from each result — you need them for all subsequent state transitions.
Creates a single recommendation in PROPOSED state. Prefer BatchCreate for multiple recommendations.
Endpoint: POST https://manage.wix.com/_api/agentic-recommendations/v1/agentic-recommendations
Request:
Response: Single agenticRecommendation object with id, revision, and state: "PROPOSED".
Query recommendations by conversation ID, state, or domain. Returns paginated results.
Endpoint: POST https://manage.wix.com/_api/agentic-recommendations/v1/agentic-recommendations/query
Request:
Filterable fields: conversationId, state, domain, urgency, id
Response:
Fetch a single recommendation by ID.
Endpoint: GET https://manage.wix.com/_api/agentic-recommendations/v1/agentic-recommendations/{agenticRecommendationId}
Response: Single agenticRecommendation object with all fields.
Get recommendation counts grouped by state for the current site.
Endpoint: POST https://manage.wix.com/_api/agentic-recommendations/v1/agentic-recommendations/count
Request: {}
Response:
Update a PROPOSED recommendation. Only title, reasoning, urgency, advice, and expiresAt can be updated. State stays PROPOSED.
Endpoint: PATCH https://manage.wix.com/_api/agentic-recommendations/v1/agentic-recommendations/{agenticRecommendationId}
Request:
Response: Updated agenticRecommendation with incremented revision.
Constraint: Only works on PROPOSED recommendations. Non-PROPOSED returns INVALID_STATE_TRANSITION.
PROPOSED → APPROVED. Call when the merchant agrees with a recommendation.
Endpoint: POST https://manage.wix.com/_api/agentic-recommendations/v1/agentic-recommendations/{agenticRecommendationId}/approve
Request:
Response: Updated agenticRecommendation with state: "APPROVED" and incremented revision.
PROPOSED → REJECTED. Call when the merchant declines.
Endpoint: POST https://manage.wix.com/_api/agentic-recommendations/v1/agentic-recommendations/{agenticRecommendationId}/reject
Request:
| Field | Type | Required | Description |
|---|---|---|---|
revision | int64 | Yes | Current revision for optimistic locking |
reason | string | No | Why the merchant rejected (max 1000 chars) |
permanent | boolean | No | If true, permanently blocks this action type for this site |
Response: Updated agenticRecommendation with state: "REJECTED".
APPROVED → EXECUTING. Call immediately before applying the recommendation.
Endpoint: POST https://manage.wix.com/_api/agentic-recommendations/v1/agentic-recommendations/{agenticRecommendationId}/mark-executing
Request:
Response: Updated agenticRecommendation with state: "EXECUTING" and incremented revision.
EXECUTING → DONE. Call after the recommendation was successfully applied.
Endpoint: POST https://manage.wix.com/_api/agentic-recommendations/v1/agentic-recommendations/{agenticRecommendationId}/mark-done
Request:
Response: Updated agenticRecommendation with state: "DONE" and executionResult.
EXECUTING → FAILED. Call when execution fails.
Endpoint: POST https://manage.wix.com/_api/agentic-recommendations/v1/agentic-recommendations/{agenticRecommendationId}/mark-failed
Request:
Response: Updated agenticRecommendation with state: "FAILED" and executionResult.
| Error | HTTP | Meaning |
|---|---|---|
| RECOMMENDATION_SUPPRESSED | 400 | Action + site blocked by permanent rejection |
| INVALID_STATE_TRANSITION | 400 | Wrong source state for the requested transition |
| VERSION_MISMATCH | 400 | Optimistic lock conflict — re-fetch and retry |
| RECOMMENDATION_NOT_FOUND | 404 | ID doesn't exist |
On VERSION_MISMATCH: Query to get the latest revision, then retry the operation with the updated revision.
Every recommendation flow MUST follow this lifecycle:
Rules:
revision from the previous API response