@wix/agent-skills 1.17.0 → 1.18.0

package/skills/wix-manage/references/google-ads/manage-campaign-success-guide.md

@@ -0,0 +1,141 @@
+---
+name: "Manage a Campaign Success Guide"
+description: "Retrieves and manages the campaign success guide for an existing Wix Google Ads Performance Max Leads campaign. Offer it after creating a supported campaign, even while it is learning or has no metrics; that proactive offer requires approval before retrieval. A direct request to improve a campaign, see what to fix next, or show the guide is already approval to retrieve it. Also use when a user reports completing or wants to reopen a guide item. Treat a clear completion report as an actionable update request even when phrased as a statement. Covers campaign selection, prioritized guide retrieval, and suggestion status updates without redundant confirmation. REST base https://www.wixapis.com/pa-platform/suggestions/v1."
+---
+# RECIPE: Manage a Campaign Success Guide
+
+A campaign success guide is a prioritized list of improvements for an **existing** Google Ads `PERFORMANCE_MAX_LEADS` campaign. Offer it as a useful next step after [creating a Performance Max campaign](create-performance-max-campaign.md). Once Create Campaign returns the campaign ID, ask whether the user wants to retrieve the guide; call the API only after they approve. There is no need to wait for the campaign to leave `LEARNING` or generate performance metrics because the guide analyzes the landing page, campaign configuration, and relevant site connections rather than depending on campaign performance data.
+
+Also use this recipe for requests such as "How can I improve my campaign?", "What should I fix next?", "Show my campaign success guide", "I made the call-to-action button clearer as the success guide recommended", "Mark this recommendation complete", or "Reopen that guide item."
+
+A direct request to improve a campaign, see what to fix next, or show its success guide is itself approval to retrieve the guide once the campaign is identified. Do not ask whether the user wants the guide after they have already made one of those requests. Separate approval is needed only when you proactively offer the guide after campaign creation.
+
+This differs from [Get AI Campaign Suggestions](get-campaign-suggestions.md), which generates keywords, budgets, locations, copy, images, and other inputs used while **building** a campaign. Do not route pre-campaign keyword, budget, creative, or targeting generation here.
+
+Base URL: `https://www.wixapis.com/pa-platform/suggestions/v1`. `<AUTH>` is the `Authorization` header; body calls also need `Content-Type: application/json`.
+
+## Resolve the campaign
+
+The guide endpoints require a campaign UUID, but users often provide only a campaign name or say "my campaign."
+
+1. If the user provides a campaign UUID, use it.
+2. Otherwise follow [Manage Campaign Lifecycle](manage-campaign-lifecycle.md) and call:
+
+   ```bash
+   curl -X GET 'https://www.wixapis.com/google-ads/v1/campaigns' \
+     -H 'Authorization: <AUTH>'
+   ```
+
+   Read each campaign's `id`, `name`, `campaignType`, and `status`.
+3. Select a campaign only when one result clearly matches the user's wording. If none or multiple plausibly match, show concise choices and ask the user to choose; never guess.
+4. Continue only for `campaignType: "PERFORMANCE_MAX_LEADS"`. If the selected campaign has another type, explain that campaign success guides currently support Google Ads Performance Max Leads campaigns only. For a supported campaign, do not gate guide retrieval on `status` or query analytics first: `LEARNING` and missing performance metrics are not reasons to wait.
+
+The common flow always sends `platformType: "GOOGLE"`; do not ask the user to provide it.
+
+## Retrieve or create the guide
+
+```bash
+curl -X POST \
+  'https://www.wixapis.com/pa-platform/suggestions/v1/campaign-success-guides/get-or-create' \
+  -H 'Authorization: <AUTH>' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "campaignId": "7d4a9c2e-86f1-4b37-a2d5-9e18c6f043ab",
+    "platformType": "GOOGLE"
+  }'
+```
+
+```json
+{
+  "campaignSuccessGuide": {
+    "id": "7d4a9c2e-86f1-4b37-a2d5-9e18c6f043ab",
+    "url": "https://www.example.com/request-a-quote",
+    "suggestions": [
+      {
+        "id": "131b82f1-44f5-4f32-8cf1-f783a5f35222",
+        "type": "CLEAR_CTA_COPY",
+        "status": "OPEN"
+      }
+    ]
+  }
+}
+```
+
+The first call may analyze the landing page, campaign configuration, and relevant site connections and can take up to **120 seconds**. Later calls normally return the saved guide unless campaign changes require another analysis. Wait for the request; do not retry prematurely. If execution times out with an unknown outcome, report the uncertainty and retrieve the guide later instead of immediately triggering another analysis.
+
+Present only the suggestions the API returns and preserve their order; `suggestions` is already in priority order. An empty array means no currently detected items need attention, not an API failure. Show `campaignSuccessGuide.url` when it helps identify the analyzed landing page.
+
+`OPEN` means pending action. `COMPLETED` means the user marked the item completed; it does **not** mean the API changed the site or campaign for them.
+
+## Translate suggestion types for the user
+
+Keep the enum value unchanged in API calls, but use these labels when explaining the guide:
+
+| Enum | User-facing meaning |
+| --- | --- |
+| `CLEAR_CTA_COPY` | Clarify the primary call-to-action button's conversion intent. |
+| `ABOVE_THE_FOLD_CTA` | Put a call-to-action where visitors can see it without scrolling. |
+| `HEADER_MATCH` | Align the landing-page heading with the campaign's ad headlines. |
+| `CONVERSION_POINT` | Add a visible lead form or booking action. |
+| `GOOGLE_REVIEWS` | Display Google reviews or ratings. |
+| `TESTIMONIAL` | Add customer testimonials attributed to named people. |
+| `CONTACT_AND_CREDIBILITY` | Display a phone number and email address. |
+| `FAQ_SECTION` | Add a visible FAQ section. |
+| `MINIMIZE_FORM_FIELDS` | Limit the lead form to four visible fields. |
+| `SOCIAL_CHANNELS` | Add a visible social profile link. |
+| `GOOGLE_MERCHANT_CENTER_CONNECTION` | Connect Google Merchant Center. |
+| `GOOGLE_BUSINESS_PROFILE_CONNECTION` | Connect a Google Business Profile. |
+| `GOOGLE_ADS_SEARCH_THEMES` | Configure Google Ads search themes. |
+| `MOBILE_OPTIMIZATION` | Improve mobile optimization. |
+| `SITE_SPEED` | Improve site speed. |
+
+## Mark an item completed or reopen it
+
+The update endpoint identifies the suggestion by its **`type`**, not its suggestion `id`. A clear statement that the user completed a specific guide recommendation—for example, "I made the call-to-action button clearer as the success guide recommended"—is an actionable request to mark that item `COMPLETED`, not merely an FYI. Do not require the user to turn it into a question or ask for redundant confirmation.
+
+Before executing an update:
+
+1. Identify the campaign and a suggestion `type` currently present in its latest guide.
+2. Match the user's wording to one returned suggestion and infer the requested status only when it is clear: a statement that they completed the recommendation means `COMPLETED`; a request to reopen it means `OPEN`.
+3. Execute immediately when the campaign, suggestion, and status are unambiguous. Ask one targeted clarification only when any of them is unclear; never guess.
+
+Mark an item completed:
+
+```bash
+curl -X POST \
+  'https://www.wixapis.com/pa-platform/suggestions/v1/campaign-success-guides/7d4a9c2e-86f1-4b37-a2d5-9e18c6f043ab/update-suggestion-status' \
+  -H 'Authorization: <AUTH>' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "type": "CLEAR_CTA_COPY",
+    "status": "COMPLETED"
+  }'
+```
+
+Reopen the same item by sending:
+
+```json
+{
+  "type": "CLEAR_CTA_COPY",
+  "status": "OPEN"
+}
+```
+
+The response wraps the updated guide as `{ "campaignSuccessGuide": { ... } }`. Treat that returned guide as the new source of truth: report the changed tracking status and summarize remaining `OPEN` suggestions in priority order. Do not claim the underlying recommendation was implemented. Do not update multiple items unless the user's wording clearly identifies all of them.
+
+If a mutation times out with an unknown outcome, do not retry automatically. Retrieve the guide later to determine the current status first.
+
+## Errors
+
+| Error | Response behavior |
+| --- | --- |
+| `PLATFORM_NOT_SUPPORTED` | Use `GOOGLE`; do not substitute another platform value. |
+| `CAMPAIGN_TYPE_NOT_SUPPORTED` | Explain that success guides currently support Google Ads Performance Max Leads campaigns only. |
+| `SUGGESTION_NOT_FOUND` | Retrieve the latest guide and choose a `type` actually present; do not keep retrying stale data. |
+| Authentication or permission error | Stop after the first rejected campaign or guide call and explain that the current collaborator cannot access or modify it. Do not try alternate base URLs, infer that Google Ads is not installed, or probe other endpoints to bypass authorization. |
+
+## References
+
+- [Suggestions API introduction](https://dev.wix.com/docs/api-reference/business-management/marketing/ads/platform/suggestion-v1/introduction)
+- [Get or Create Campaign Success Guide](https://dev.wix.com/docs/api-reference/business-management/marketing/ads/platform/suggestion-v1/get-or-create-campaign-success-guide)
+- [Update Campaign Success Guide Suggestion Status](https://dev.wix.com/docs/api-reference/business-management/marketing/ads/platform/suggestion-v1/update-campaign-success-guide-suggestion-status)

package/skills/wix-manage/references/google-business-profile/connect-google-business-profile.md

@@ -0,0 +1,134 @@
+---
+name: "Connect a Wix Site to Google Business Profile"
+description: Connect the authenticated Wix site to a Google Business Profile account, check whether an existing connection is still usable, recover a connection whose stored credentials are gone, switch to a different Google account, or disconnect. The site owner authorizes in their own browser through a single-use connect URL; the agent never completes the Google authorization itself. Warns before any reconnect that permanently removes the site's imported locations.
+---
+
+# Connect a Wix Site to Google Business Profile
+
+Use the public **Google Business Profile Connection API** to link the
+authenticated Wix site to a Google Business Profile account. The REST requests
+do not contain a site ID — the site comes from the caller's authorization
+context. Use the site the environment already supplies; if no site is selected,
+list the user's sites once and auto-select the only one, or ask the user to
+choose by site name when several are available. Never invent a site ID or ask
+the user to type one. A connection is the prerequisite for Google-backed work in the Google
+Business Profile Locations API — establish it before importing or managing
+locations.
+
+> **Bounded connect path — read first.** Read the connection once. For
+> `NEVER_CONNECTED`, request one connect URL and hand it to the owner; for
+> `VALID`, stop unless the user asked for other Google-backed work. A `403`,
+> `PERMISSION_DENIED`, or other terminal recovery-rule error ends the flow:
+> the **next action is the final response** explaining the blocker. Make no
+> further tool call: no API probe, documentation search, alternate request
+> shape, or call against another site. Only the explicitly
+> retryable `CONNECTING_USER_LOOKUP_UNAVAILABLE` error permits another connect-URL
+> attempt.
+
+Wix stores the Google credentials server-side. The API never returns tokens or
+any Google identity — only whether a connection exists and its dates.
+
+## Direct calls for this flow
+
+These are the complete request shapes needed for a fresh connection. Use them
+directly; do not search the API reference before calling them.
+
+| Method | Call |
+|---|---|
+| **Get Connection** | `GET https://www.wixapis.com/gbp/v1/connection` — no body or parameters |
+| **Get Connect URL** | `GET https://www.wixapis.com/gbp/v1/connect-url` — no body or parameters |
+
+For the common `NEVER_CONNECTED` path the only API calls are one **Get
+Connection**, then one **Get Connect URL**. If either returns `403` or
+`PERMISSION_DENIED`, stop immediately and explain it; do not look for another
+method or request shape.
+
+## Check the status first
+
+Always start with **Get Connection** and branch on `status`:
+
+| `status` | Meaning | What to do |
+|---|---|---|
+| `VALID` | Wix holds a credential for this site | Proceed with Google-backed work |
+| `NEVER_CONNECTED` | The site has never been connected | Run the connect flow — this is a setup step, not an error |
+| `NEEDS_RECONNECT` | The connection record exists but the stored credentials are gone | Warn the owner (see below), then run the connect flow |
+
+`VALID` is not a live health check: **Get Connection** deliberately does not
+call Google, so a connection can report `VALID` and still be refused by
+Google — for example after the owner revoked Wix's access in their Google
+account settings. Treat a Google-side authorization failure on a Locations
+call as the authoritative signal and re-run the connect flow when one appears.
+
+## Run the connect flow
+
+1. Call **Get Connect URL** once and read `connectUrl`.
+2. Present `connectUrl` to the site owner as a link to open in their own
+   browser, where they sign in to Google and grant access. Never fetch or open
+   the URL yourself — it is for a human, single-use, and expires after
+   15 minutes.
+3. Explain that completion is asynchronous: Google redirects the owner's
+   browser back to Wix, which finishes the OAuth exchange and stores the
+   credentials server-side.
+4. When the owner reports they have finished (or while waiting, on a modest
+   interval of a few seconds), call **Get Connection** and confirm `status` is
+   `VALID`. The `status` field is the only source of truth — a returned
+   connect URL alone proves nothing.
+5. If the 15-minute window elapses with `status` unchanged, request a fresh
+   URL and let the owner try again.
+
+**Get Connect URL is not idempotent, despite its GET route.** Every successful
+call creates a distinct live authorization attempt. Never retry it
+automatically after a timeout or ambiguous response — re-check
+**Get Connection** first and let the owner explicitly start another attempt.
+
+## Warn before a reconnect that replaces the connection
+
+Two flows permanently remove every Business Profile location imported into the
+site — the locations created through Wix as well as the imported ones. For
+locations migrated from an earlier Wix integration this cannot be reversed by
+re-importing. Get the owner's explicit confirmation **before** handing them
+the connect URL; there is no confirmation step later:
+
+- **Switching to a different Google account.** No Disconnect is needed — the
+  new account simply replaces the connection when its authorization completes.
+- **Reconnecting from `NEEDS_RECONNECT`, even with the same Google account.**
+  The stored credentials are gone, so there is nothing to match the incoming
+  account against and the reconnect is always treated as a replacement.
+
+While credentials are still present (`VALID`), authorizing again with the
+**same** Google account heals the connection in place and removes nothing.
+
+Also tell the owner that replacing or disconnecting changes nothing inside
+Google Business Profile itself — locations, reviews, and photos stay exactly
+as they are on Google — and does not revoke Wix's access inside their old
+Google account; they remove that from their Google account settings.
+
+## Disconnect
+
+Call **Disconnect** only after the owner confirms. It deletes the credentials
+Wix stores; it does not touch the Google Business Profile and does not revoke
+Wix's grant inside the Google account.
+
+## Recovery rules
+
+- **`CONNECTING_USER_LOOKUP_UNAVAILABLE`:** the site-owner lookup failed
+  temporarily, before any authorization attempt was created. This is the one
+  failure of **Get Connect URL** that is safe to retry.
+- **`CONNECTING_USER_NOT_RESOLVABLE`:** Wix could not identify a user to own
+  the credential. Stop — this is not retryable until the caller identity or
+  site ownership is corrected. Explain the blocker instead of trying other
+  request shapes.
+- **Timeout or ambiguous response from Get Connect URL:** do not retry. Call
+  **Get Connection** to learn the actual state, then let the owner decide.
+- **`MULTIPLE_CONNECTIONS_NOT_REPRESENTABLE`:** the site holds more than one
+  connection and the API will not guess which one is meant. Not a caller error
+  and not retryable — report it and direct the user to contact Wix support.
+- **Permission denied:** stop after the first `403` or `PERMISSION_DENIED`.
+  Do not retry with another request shape or site, and do not search for an
+  alternate API or method. Explain that the current Wix identity is not
+  authorized to manage the site's Google connection.
+
+The direct calls above are self-contained for the normal connect path. Consult a
+specific public method reference only for an edge case not covered here, and
+only before making a call. Once a status or typed error selects a branch above,
+do not search or browse for an alternate API, method, or request shape.

package/skills/wix-manage/references/google-business-profile/manage-google-business-profile-locations.md

@@ -0,0 +1,182 @@
+---
+name: "Manage Google Business Profile Locations for a Wix Site"
+description: Import Google Business Profile locations into the authenticated Wix site, list and query them with or without live Google data, update Wix-side and Google-side details through the correct method for each, create a new Google listing, check whether a profile is actually live on Google, and remove a location from Wix or delete its Google listing. Checks the site's Google connection first and reports a missing one as a setup step, warns before destructive or Google-visible writes, and respects Google's shared rate budget.
+---
+
+# Manage Google Business Profile Locations for a Wix Site
+
+Use the public **Google Business Profile Locations API** to manage the
+authenticated Wix site's Business Profile locations — the entries that decide
+how the business appears on Google Search and Maps. The REST requests do not
+contain a site ID — the site comes from the caller's authorization context.
+Use the site the environment already supplies; if no site is selected, list
+the user's sites once and auto-select the only one, or ask the user to choose
+by site name when several are available. Never invent a site ID or ask the
+user to type one.
+
+> **Unconnected-site fast path — read first.** Read the connection once. Treat
+> `NEVER_CONNECTED`, `NEEDS_RECONNECT`, or a single
+> `CONNECTION_NOT_FOUND`/not-found response from that connection check as the
+> same setup state. Query Wix-only GBP locations once to answer what the site
+> already has, report the result, explain the connect → account selection →
+> unimported-location selection → bulk-create flow, and stop — after that one
+> query the **next action is the final response**, with no other tool call. Do
+> not call a Google-backed location method, probe for Business Profile
+> accounts, guess an endpoint, or make further API probes or documentation
+> searches until the connection is `VALID`. A `403` or `PERMISSION_DENIED` is
+> terminal: the **next action is the final response** explaining it. Stop
+> without the Wix-only query, documentation search, or any other tool call.
+
+The API is a live view onto Google, not a copy: most calls make a real Google
+request, with Google's latency and rate limits. A location's ID is Google's
+opaque location ID and is what identifies it everywhere.
+
+## Direct calls for the unconnected-site path
+
+Use these request shapes directly; do not search the API reference before
+calling them.
+
+| Method | Call |
+|---|---|
+| **Get Connection** | `GET https://www.wixapis.com/gbp/v1/connection` — no body or parameters |
+| **Query GBP Locations** | `POST https://www.wixapis.com/gbp/v1/locations/query` with body below |
+
+```json
+{ "query": { "paging": { "limit": 100 } } }
+```
+
+Make **Get Connection** first, then branch before making any other call:
+
+- `403` or `PERMISSION_DENIED` — stop. The next action is the final response;
+  explain that the current Wix identity cannot inspect the site's GBP state.
+  Do not query locations, inspect installed apps, search documentation, or try
+  another endpoint.
+- `NEVER_CONNECTED`, `NEEDS_RECONNECT`, or `CONNECTION_NOT_FOUND` — make one
+  **Query GBP Locations** call, report the Wix-stored result, explain the future
+  import steps, and stop. The next action is the final response.
+- `VALID` — proceed with the requested Google-backed flow.
+
+Do not call **List GBP Accounts** or another Google-backed method until the
+connection is `VALID` — account discovery requires the connection, and its
+request shape is not the locations query. Never guess an endpoint that is not
+in the table above or in the loaded reference.
+
+## Check the connection first
+
+Google-backed methods require a Google connection, established through the
+**Google Business Profile Connection API** (see the connect recipe). Before
+Google-backed work, call **Get Connection**:
+
+- `VALID` — proceed.
+- `NEVER_CONNECTED` or `NEEDS_RECONNECT` — report a setup step, not an error,
+  and offer to run the connect flow. Do not retry location calls until the
+  connection is `VALID`.
+
+Wix-only reads and deletes still work without active Google credentials:
+**Get GBP Location**, **Query GBP Locations**, **Update Location**,
+**Delete Location**, and **Bulk Delete Locations**.
+
+## Import locations
+
+Importing registers listings that already exist at Google; it never creates
+one. Each step narrows the next:
+
+1. Call **List GBP Accounts**. One Google login can hold several Business
+   Profile accounts, so present the list and let the owner pick — never assume
+   the first one.
+2. Call **List Unimported Locations** with the chosen `accountId`. It returns
+   only what the site hasn't imported yet, so re-running never offers
+   duplicates.
+3. Let the owner select which locations to import, and confirm before writing.
+4. Call **Bulk Create Locations** with the selected locations, supplying `id`
+   and `accountId` on each.
+5. Inspect every `results[].itemMetadata.error`. The call reports per-item
+   failures instead of aborting, so a `200` does not mean every location
+   imported. Report failures explicitly.
+
+Repeat steps 2–5 per account if the owner wants locations from more than one.
+
+## List and query locations
+
+Choose by whether live Google data is needed:
+
+- **Just the site's locations:** call **Query GBP Locations**. Wix-stored rows
+  only — fast, no Google round-trip, no Google rate limit. Use it for counts,
+  ID lookups, and anything driven by `id`, `googleLocationId`, or `accountId`.
+- **Locations with live business details:** call **Query Google Locations**
+  (or **Get Google Location** for one). Each row is hydrated with a live
+  Google fetch. Check each row for `googleError` — one location failing at
+  Google does not fail the request or break paging, so render it as a
+  per-location problem, not an empty result.
+
+## Update the correct side
+
+Wix stores almost nothing; the method name tells you which side a write
+reaches. Check before calling anything destructive:
+
+| Method | Wix row | Google listing |
+|---|---|---|
+| **Create Location**, **Bulk Create Locations** | created | untouched (imports an existing listing) |
+| **Create Google Location** | created | **created** |
+| **Update Location** | updated | untouched (writes Wix-stored fields only) |
+| **Update Google Location** | untouched | **updated** |
+| **Delete Location**, **Bulk Delete Locations** | deleted | untouched |
+| **Delete Google Location** | deleted | **deleted** |
+
+- **Update Location** is not the way to edit a Business Profile — it writes
+  only Wix-stored fields. To change Google-owned data (title, address, hours,
+  categories), call **Update Google Location**, and confirm with the owner
+  first: the change is publicly visible on Google.
+- To create a brand-new Google listing, call **Create Google Location** after
+  explicit confirmation. Use the API's reference-data methods (address schema,
+  category and region suggestions) rather than inventing values.
+- Google allows roughly 10 profile edits per minute per Business Profile, and
+  the budget is shared across every write method. Pace the profile as a whole
+  and treat a `429` as worth retrying after a delay, not as a rejection.
+
+## Remove a location
+
+Decide first whether the owner is removing it from Wix or deleting the real
+Google listing — these are different operations and one is irreversible.
+Confirm which they mean before calling anything:
+
+- **Un-import from Wix, leave Google alone:** call **Delete Location**, or
+  **Bulk Delete Locations** for several. Inspect every
+  `results[].itemMetadata` entry — the bulk call can partially succeed.
+- **Delete the Google listing as well:** call **Delete Google Location** once
+  per location; there is no bulk Google delete. Require explicit confirmation
+  naming the location — the listing disappears from Google Search and Maps.
+- If **Delete Google Location** returns `LOCATION_DB_PERSIST_FAILED`, Google
+  deleted the listing but Wix didn't record it. The error payload carries the
+  location ID; call **Delete Location** with it to reconcile.
+
+## Check whether a profile is actually live
+
+A location existing in Wix does not mean it appears on Google — verification
+can be pending, the profile suspended, or ownership contested. Call
+**Get Voice of Merchant** for the location and act on what Google reports:
+wait, verify, comply, or resolve the conflict.
+
+## Recovery rules
+
+- **`FAILED_PRECONDITION` with `CONNECTION_NOT_FOUND`:** the site has no
+  usable Google connection. Report the setup step and offer the connect flow;
+  do not retry the same call.
+- **`GOOGLE_API_CALL_FAILED`:** read the carried Google code and description.
+  Some failures are permanent (profile suspended, field not editable) —
+  retrying will not help; explain instead.
+- **Per-row `googleError` on hydrating reads:** report it per location and
+  continue with the rest of the page.
+- **Rate limited (`429`):** wait, then retry; interleaved writes share one
+  budget per profile.
+- **Permission denied:** stop after the first `403` or `PERMISSION_DENIED`.
+  Do not retry with other locations, request shapes, or sites, and do not
+  search for an alternate API or method. Deleting locations requires the
+  site's `GBP_ADMIN` role.
+
+The same API also covers reviews and replies, photos and bulk media uploads,
+attributes, verification, performance insights, and location admins — load the
+specific public method reference needed before constructing a request so field
+names, filters, permissions, and errors come from the live contract. Once a
+connection state or typed error selects a branch above, do not search or browse
+for an alternate API, method, or request shape.

package/skills/wix-manage/references/marketing/create-and-publish-social-post.md

@@ -359,6 +359,8 @@ Build the request from `item.channel` (`name` + the `accountId` from STEP 4b), `
 - Otherwise, build it from the STEP 3 table row for your channel + `type`: the text field (`caption` for Instagram/Facebook/LinkedIn/X, `description` for YouTube/Pinterest/GBP/TikTok), the media (`mediaWrapper`, or `imageUrl`/`videoUrl` for a single item), and any channel-specific IDs from the STEP 4b account object, plus `title` where the channel uses one.
 - Instagram and story types require media.
 
+**Attribution (always set this).** Set `item.consumerInfo` to `{ "name": "wix-skills-social" }` on **every** create-draft call, for every channel. `consumerInfo.name` identifies what created the post — the Social Media Marketing dashboard sets `social-marketing`, and this recipe sets `wix-skills-social`. Set it on the draft: `name` is applied on creation only, and Update Item ignores it.
+
 **Idempotency (retry safety).** Set a stable, caller-defined `item.referenceId` on the draft. The Publisher enforces its uniqueness — a second item created/published with the same `referenceId` is rejected with `REFERENCE_ID_ALREADY_EXIST` instead of posting a duplicate. So if a create or publish call times out, retry with the **same** `referenceId` rather than risk double-posting.
 
 **Example — Instagram image post:**
@@ -368,6 +370,7 @@ Build the request from `item.channel` (`name` + the `accountId` from STEP 4b), `
   "item": {
     "channel": { "name": "INSTAGRAM", "accountId": "17841405822304914" },
     "type": "POST",
+    "consumerInfo": { "name": "wix-skills-social" },
     "instagramPost": {
       "imageUrl": "https://static.wixstatic.com/media/cf2434_4b3a2d8eb7f54bc89c0d4524430a2af3~mv2.jpg",
       "caption": "Summer collection just dropped! Shop the look now. #summerstyle #newarrivals"

package/skills/wix-manage/references/stores/create-product-catalog-v3.md

@@ -65,14 +65,14 @@ If any product is missing a price, **do not call the API**. Ask for the missing
 - Bulk endpoints accept 1–100 products, so a compatible bulk endpoint is also valid for one product.
 - For multiple products requested as one batch, send one bulk call. Use the with-inventory endpoint when any product needs inventory; include `inventoryItem` only on tracked variants.
 - Never send `inventoryItem` to a no-inventory endpoint. Do not invent inventory.
-- Digital products normally use a no-inventory endpoint.
+- Digital products use a with-inventory endpoint: an unstocked digital variant is unsellable.
 - Per bulk request, allow at most 100 products, 100 total options, 100 modifiers, 100 info sections, and 1000 variants. Split larger input into compliant batches.
 
 ## Build each product
 
 | Concern | Rule |
 |---|---|
-| Type | `PHYSICAL` uses product- and variant-level `physicalProperties`; `DIGITAL` omits physical properties and inventory. |
+| Type | `PHYSICAL` uses product- and variant-level `physicalProperties`; `DIGITAL` omits them and carries `inventoryItem.inStock` plus `digitalProperties.digitalFile` on each variant. |
 | Variants | Include at least one. Price, SKU, barcode, inventory, and digital file are variant-level fields. |
 | Price | Use a string in `price.actualPrice.amount`; add `compareAtPrice` only when supplied. |
 | SKU | Preserve supplied strings exactly, including `#`, punctuation, and leading zeroes. Keep variant SKUs unique unless explicitly requested otherwise. |
@@ -127,9 +127,20 @@ This inventory-aware physical product is the reusable shape. Remove `inventoryIt
 }
 ```
 
-For a color option, use `SWATCH_CHOICES`; each choice uses `choiceType: ONE_COLOR` and `colorCode`, and the variant reference uses `renderType: SWATCH_CHOICES`.
+For a color option, use `SWATCH_CHOICES`; each choice uses `choiceType: ONE_COLOR` and `colorCode`, and the variant reference uses `renderType: SWATCH_CHOICES`. For a different **image** per colour (not just the swatch), each choice also carries its own `media`:
 
-A digital product uses the smaller shape below. Add the supplied variant-level digital file only when one was provided.
+```json
+"choicesSettings": {"choices": [
+  {"choiceType": "ONE_COLOR", "name": "Black", "colorCode": "#000000",
+   "media": {"items": [{"url": "https://static.wixstatic.com/media/<black>.jpg"}]}},
+  {"choiceType": "ONE_COLOR", "name": "White", "colorCode": "#FFFFFF",
+   "media": {"items": [{"url": "https://static.wixstatic.com/media/<white>.jpg"}]}}
+]}
+```
+
+The image must be in the product gallery first, and the id/ordering has a trap — assign per-choice media via **[Update Product with Options](update-product-with-options.md) → Choice & variant fields** (also the full choice-vs-variant field split: choice `media`/`colorCode`; variant `price`/`sku`/`barcode`/stock).
+
+A digital variant is **sellable** only when it carries both a digital file and stock; miss either and the product reads back healthy and is rejected at add-to-cart. Upload the file first ([Upload Media to Wix](../media/upload-media-to-wix.md) → Generate Upload URL, then `PUT` the bytes) and send the returned `file.id` to `POST /stores/v3/products-with-inventory`:
 
 ```json
 {
@@ -138,11 +149,15 @@ A digital product uses the smaller shape below. Add the supplied variant-level d
   "variantsInfo": {"variants": [{
     "sku": "PDF-FOCUS-01",
     "price": {"actualPrice": {"amount": "9.99"}},
-    "visible": true
+    "visible": true,
+    "inventoryItem": {"inStock": true},
+    "digitalProperties": {"digitalFile": {"id": "<FILE_ID>"}}
   }]}
 }
 ```
 
+With no file supplied, create the product and report it as not sellable until one is attached — [Update Product with Options](update-product-with-options.md) → Attach a digital file.
+
 ### Generated descriptions and SEO
 
 - When copy is generated from an image, every factual claim must be user-supplied or directly visible. Preserve user-supplied facts such as a stated material; do not reject them merely because the image alone cannot prove them. Color, shape, and visible decoration may come from the image. Dimensions, capacity, care instructions, durability, compatibility, performance, and any material the user did not identify must be omitted. For example, never write “dishwasher safe” or “microwave safe” unless the user supplied that fact. Omit uncertain claims instead of turning them into marketing language.
@@ -270,4 +285,4 @@ Retry only failed transient items, not successful products. If a requested field
 - `variantsInfo must not be empty`: include at least one priced variant per product.
 - Option/variant mismatch: create every requested combination and reference every option once per variant.
 - Media not visible: use the uploaded `wixstatic.com` URL in `media.itemsInfo.items`; do not set `media.main`.
-- Digital product rejected: omit physical properties and inventory; keep price, SKU, and any supplied digital file on the variant.
+- Digital product rejected at add-to-cart: `ITEM_NOT_FOUND_IN_CATALOG` means the variant has no `digitalProperties.digitalFile`; `exceeds available inventory` means it has no `inventoryItem.inStock`. Both read back as a healthy product.

package/skills/wix-manage/references/stores/update-product-with-options.md

@@ -275,6 +275,8 @@ curl -X POST "https://www.wixapis.com/stores/v3/bulk/inventory-items/create" \
 
 ### Update Media Only
 
+Sets the product-level gallery (`media.itemsInfo.items`). For an image shown per option choice (a swatch's photo), see **Per-choice media** below.
+
 ```bash
 curl -X PATCH "https://www.wixapis.com/stores/v3/products/{productId}" \
   -H "Content-Type: application/json" \
@@ -297,6 +299,56 @@ curl -X PATCH "https://www.wixapis.com/stores/v3/products/{productId}" \
   }'
 ```
 
+### Choice & variant fields (what you can set)
+
+Send these inside the `options` / `variantsInfo.variants` arrays — **both arrays complete, in the
+same PATCH**, with the current `revision`, and **identity-preserving** (see *Update Options and
+Variants*): keep the option's `id` and every `choiceId`, or the ids are re-minted and the existing
+variants no longer resolve (`400 "Variant choice not found in product options"`). Each variant needs
+its `id`, its `choices` (by `optionChoiceIds` — or `optionChoiceNames`, see *Gotchas*) **and** a
+`price` — omitting price is `400 "price must not be empty"`.
+
+**Option choice** (`options[].choicesSettings.choices[]`):
+- `name`, `choiceType`, `colorCode` — the choice's identity and swatch colour.
+- `media` = `{ "items": [ { "mediaId" } | { "url" } ] }` — the product photos shown when this choice is picked. `url` is write-only; on read you get `mediaId` (request the `PRODUCT_CHOICES_MEDIA_REFERENCES` mask). Use `media`, **not** `linkedMedia` (a separate display-filter, returned empty when you read `media`).
+  - **Gallery-first; the id you link is the gallery item's, not the upload's.** Add the `url` to the gallery, then read the product back and link the id you see there:
+
+    ```
+    GET /stores/v3/products/{id}?fields=MEDIA_ITEMS_INFO
+    #  → media.itemsInfo.items[].id = "abc~mv2.jpg"   ← link THIS as choice media.items[].mediaId
+    # the id from POST /site-media/v1/files/import or /files/get-file-by-id 400s as a choice mediaId
+    ```
+    `{ "url" }` works in place of `{ "mediaId" }` too, but only once the image is already in the gallery.
+- `displayImage` — the image shown on the swatch itself (distinct from `media`).
+- Read-only, don't send: `inStock`, `visible`, `key`.
+
+**Variant** (`variantsInfo.variants[]`, by its `id` from Get Product; always send `choices` + `price` with it):
+- `price` = `{ "actualPrice": { "amount" }, "compareAtPrice": { "amount" } }` — set `compareAtPrice` above `actualPrice` for a strikethrough sale; omit it for full price.
+- `sku`, `barcode` — per combination.
+- `visible` — hide a single variant.
+- `revenueDetails` — cost / profit tracking.
+- Read-only, don't send: `media` (derived from the choices' media), `inventoryStatus` (stock — use the Inventory API, see *Set Stock for New Variants*), `subscriptionPricesInfo`.
+
+```bash
+# A choice image + a variant's sale price, one PATCH. Both arrays are complete and keep their ids —
+# this exact shape is the one that succeeds; the two shortcuts (choices by name only, or a variant
+# without its choices/price) each 400.
+curl -X PATCH "https://www.wixapis.com/stores/v3/products/{productId}" \
+  -H "Content-Type: application/json" -H "Authorization: <AUTH>" \
+  -d '{ "product": { "id": "{productId}", "revision": "{currentRevision}",
+        "options": [ { "id": "{optionId}", "name": "Color", "optionRenderType": "COLOR_CHOICES",
+          "choicesSettings": { "choices": [
+            { "choiceId": "{choiceId1}", "name": "Red", "choiceType": "ONE_COLOR", "colorCode": "#C0392B",
+              "media": { "items": [ { "mediaId": "abc~mv2.jpg" } ] } },
+            { "choiceId": "{choiceId2}", "name": "Blue", "choiceType": "ONE_COLOR", "colorCode": "#2C3E50" } ] } } ],
+        "variantsInfo": { "variants": [
+          { "id": "{variantId1}", "sku": "TEE-RED-L",
+            "price": { "actualPrice": { "amount": "20" }, "compareAtPrice": { "amount": "30" } },
+            "choices": [ { "optionChoiceIds": { "optionId": "{optionId}", "choiceId": "{choiceId1}" } } ] },
+          { "id": "{variantId2}", "price": { "actualPrice": { "amount": "20" } },
+            "choices": [ { "optionChoiceIds": { "optionId": "{optionId}", "choiceId": "{choiceId2}" } } ] } ] } } }'
+```
+
 ### Update Variant Price Only
 
 Read `{existingVariantId}` off the Get Product response; a Search or Query Products result does not carry it.
@@ -325,6 +377,35 @@ curl -X PATCH "https://www.wixapis.com/stores/v3/products/{productId}" \
   }'
 ```
 
+### Attach a Digital File
+
+A `DIGITAL` product is **sellable** only when its variant carries both a digital file and stock. Upload the file first ([Upload Media to Wix](../media/upload-media-to-wix.md) → Generate Upload URL, then `PUT` the bytes), then send its `file.id` on the variant — `digitalProperties` is a variant field, never a product field.
+
+```bash
+curl -X PATCH "https://www.wixapis.com/stores/v3/products/{productId}" \
+  -H "Content-Type: application/json" \
+  -H "Authorization: <AUTH>" \
+  -d '{
+    "product": {
+      "id": "{productId}",
+      "revision": "{currentRevision}",
+      "variantsInfo": {
+        "variants": [
+          {
+            "id": "{existingVariantId}",
+            "price": { "actualPrice": { "amount": "9.99" } },
+            "visible": true,
+            "inventoryItem": { "inStock": true },
+            "digitalProperties": { "digitalFile": { "id": "{fileId}" } }
+          }
+        ]
+      }
+    }
+  }'
+```
+
+Confirm from `product.variantsInfo.variants[].digitalProperties.digitalFile` in the response.
+
 ## Important Notes
 
 - A request to hide a product is a `visible: false` update on the product, never a Delete Product call and never a variant-only change.
@@ -348,3 +429,5 @@ curl -X PATCH "https://www.wixapis.com/stores/v3/products/{productId}" \
 | `variantsInfo is invalid: variants has size 0, expected 1 or more` | Variants were read from a Search or Query Products response, which does not return them | Re-read the product with Get Product and send its `variantsInfo.variants` |
 | `Missing option choices` or `INVALID_DEFAULT_VARIANT` | Product has options but at least one variant has no matching choices | Rebuild `variantsInfo.variants` so every variant includes choices for all product options |
 | `DIGITAL_PRODUCT_CANNOT_BE_VISIBLE_IN_POS` | Sent `visibleInPos: true` on a digital product | Digital products can't be visible in POS; leave `visibleInPos` out of the body |
+| `ITEM_NOT_FOUND_IN_CATALOG` at add-to-cart, product exists | A `DIGITAL` variant has no `digitalProperties.digitalFile` | Attach a file — see [Attach a Digital File](#attach-a-digital-file) |
+| `exceeds available inventory` at add-to-cart, product exists | The variant has no stock (`DIGITAL` products included) | Set `inventoryItem.inStock: true` on the variant |