/wix-manage

API: Recommendation Tracking Service

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

Internal-but-callable API. This is a Wix-internal service with NO public dev.wix.com docs page. It IS callable via CallWixSiteAPI in the authenticated editor/dashboard context the MCP runs in (verified: the endpoints return auth/validation errors, not 404). This file is the authoritative spec — do not try to ReadFullDocsArticle an external doc for it.

How to call these APIs

Use CallWixSiteAPI to invoke each endpoint:

CallWixSiteAPI(
  url: "https://manage.wix.com/_api/agentic-recommendations/v1/agentic-recommendations/<endpoint>",
  method: "POST",
  body: { ... }
)

Data Model

Recommendation

Advice

ExecutionResult

State Machine

PROPOSED → APPROVED → EXECUTING → DONE
    │                      └──→ FAILED
    ├──→ REJECTED
    └──→ EXPIRED (scheduler)

BatchCreate

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:

{
  "agenticRecommendations": [
    {
      "title": "15% Off Electronics — Orders Over $200",
      "reasoning": "AOV is $165. Electronics avg margin 42%. $200 threshold incentivizes adding one more item.",
      "domain": "discounts",
      "urgency": "HIGH",
      "advice": {
        "action": "apply_discount",
        "params": {
          "mechanism": "AUTOMATIC",
          "scope": "CATEGORY",
          "discountType": "PERCENTAGE",
          "discount": 15,
          "conditions": { "minSubTotal": 200 }
        },
        "successCriteria": "15% discount applied to Electronics for orders above $200"
      }
    }
  ],
  "conversationId": "<conversationId>"
}

Response:

{
  "results": [
    {
      "agenticRecommendation": {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "revision": "1",
        "state": "PROPOSED",
        "title": "15% Off Electronics — Orders Over $200",
        "reasoning": "...",
        "domain": "discounts",
        "urgency": "HIGH",
        "advice": { "..." : "..." },
        "conversationId": "...",
        "createdDate": "2026-05-10T10:00:00Z",
        "updatedDate": "2026-05-10T10:00:00Z"
      }
    }
  ]
}

Important: Save the id and revision from each result — you need them for all subsequent state transitions.

Create

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:

{
  "agenticRecommendation": {
    "title": "Add Free Shipping for Orders Over $75",
    "reasoning": "No free shipping option. delivery_step_cvr is 48%, below 65% benchmark. AOV is $62.",
    "domain": "shipping",
    "urgency": "HIGH",
    "advice": {
      "action": "create_shipping_option",
      "params": {
        "category": "free_shipping",
        "ids": ["region-guid"],
        "rates": [{ "amount": "0", "conditions": [{ "type": "BY_TOTAL_PRICE", "operator": "GTE", "value": "75" }] }]
      },
      "successCriteria": "Free shipping option created for orders above $75"
    },
    "conversationId": "<conversationId>"
  }
}

Response: Single agenticRecommendation object with id, revision, and state: "PROPOSED".

Query

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:

{
  "query": {
    "filter": {
      "conversationId": "<conversationId>",
      "state": { "$in": ["PROPOSED", "APPROVED"] }
    },
    "cursorPaging": { "limit": 50 }
  }
}

Filterable fields: conversationId, state, domain, urgency, id

Response:

{
  "agenticRecommendations": [
    {
      "id": "a1b2c3d4-...",
      "revision": "1",
      "state": "PROPOSED",
      "title": "...",
      "domain": "discounts",
      "urgency": "HIGH",
      "advice": { "..." : "..." }
    }
  ],
  "pagingMetadata": { "count": 1, "cursors": {}, "hasNext": false }
}

Get

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.

Count

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:

{
  "counts": {
    "PROPOSED": 3,
    "APPROVED": 1,
    "EXECUTING": 0,
    "DONE": 5,
    "FAILED": 1,
    "REJECTED": 2
  }
}

Update

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:

{
  "agenticRecommendation": {
    "id": "a1b2c3d4-...",
    "revision": "1",
    "advice": {
      "action": "apply_discount",
      "params": { "discount": 20 },
      "successCriteria": "20% discount applied"
    }
  },
  "fieldMask": { "paths": ["advice"] }
}

Response: Updated agenticRecommendation with incremented revision.

Constraint: Only works on PROPOSED recommendations. Non-PROPOSED returns INVALID_STATE_TRANSITION.

Approve

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:

{
  "revision": "1"
}

Response: Updated agenticRecommendation with state: "APPROVED" and incremented revision.

Reject

PROPOSED → REJECTED. Call when the merchant declines.

Endpoint: POST https://manage.wix.com/_api/agentic-recommendations/v1/agentic-recommendations/{agenticRecommendationId}/reject

Request:

{
  "revision": "1",
  "reason": "Merchant prefers flat-rate discount instead",
  "permanent": false
}

Response: Updated agenticRecommendation with state: "REJECTED".

MarkExecuting

APPROVED → EXECUTING. Call immediately before applying the recommendation.

Endpoint: POST https://manage.wix.com/_api/agentic-recommendations/v1/agentic-recommendations/{agenticRecommendationId}/mark-executing

Request:

{
  "revision": "2"
}

Response: Updated agenticRecommendation with state: "EXECUTING" and incremented revision.

MarkDone

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:

{
  "revision": "3",
  "executionResult": {
    "status": "SUCCESS",
    "summary": "Created 15% discount rule for Electronics with $200 minimum"
  }
}

Response: Updated agenticRecommendation with state: "DONE" and executionResult.

MarkFailed

EXECUTING → FAILED. Call when execution fails.

Endpoint: POST https://manage.wix.com/_api/agentic-recommendations/v1/agentic-recommendations/{agenticRecommendationId}/mark-failed

Request:

{
  "revision": "3",
  "executionResult": {
    "status": "FAILURE",
    "summary": "Failed to create discount rule",
    "error": "REVISION_MISMATCH: discount rule was modified by another process"
  }
}

Response: Updated agenticRecommendation with state: "FAILED" and executionResult.

Error Codes

On VERSION_MISMATCH: Query to get the latest revision, then retry the operation with the updated revision.

Integration pattern for all recommendation flows

Every recommendation flow MUST follow this lifecycle:

Step 1: Generate recommendations (domain-specific analysis)
Step 2: BatchCreate → persist ALL recommendations as PROPOSED (save id + revision for each)
Step 3: Present recommendations to merchant (include id + revision)
Step 4: On each merchant action:
  - APPROVE: Approve → MarkExecuting → apply the change → MarkDone or MarkFailed
  - REJECT:  Reject (with reason, permanent flag)
  - MODIFY:  Update (field mask) → stays PROPOSED → re-present

Rules:

• Every recommendation MUST be persisted before presenting to the merchant
• Always use the latest revision from the previous API response
• Track ALL outcomes — both success (MarkDone) and failure (MarkFailed)
• On VERSION_MISMATCH: re-fetch with Query, get latest revision, retry
• Never skip the EXECUTING state — always call MarkExecuting before applying