@wix/agent-skills 1.16.3 → 1.18.0

package/skills/wix-manage/references/seo/manage-url-redirects.md

@@ -0,0 +1,250 @@
+---
+name: "Manage URL Redirects on a Wix Site"
+description: "Retrieve, create, and delete URL redirects on a Wix site using the public SEO Redirects API. Covers exact and group redirects, language-scoped redirects for multilingual sites, batches of up to 500, and the change flow for a redirect that already exists. This API has no query, search, or update method: List Redirects is the only read-many. Redirects do not chain, so creating one that points at a path another redirect starts from permanently deletes that other redirect; list and check before every write."
+---
+
+# Manage URL Redirects on a Wix Site
+
+Use the public **SEO Redirects API** to manage where a Wix site sends visitors who
+request an old or moved URL. The API selects the site from the caller's
+authorization context.
+
+If the run already identifies a site - one connected site, or a site ID supplied
+by the environment - use it and continue. Ask which site only when several are
+available and nothing in the request or the context picks one. Do not stop to ask
+for a site ID the API never takes.
+
+A redirect returns a 301 permanent redirect, takes effect on the live site
+immediately with no site publish, and **takes precedence over a real page at the
+same path**. Creating a redirect from a path that still serves a page makes that
+page unreachable until the redirect is deleted.
+
+## Redirects do not chain, they replace
+
+This is the single most important thing to know, and it is not what most agents
+assume. If an existing redirect **starts at** the path your new redirect points
+to, the two do not form a chain. The existing one is **deleted**, and your create
+proceeds.
+
+So with `/blog` -> `/news` already on the site, creating `/old-blog` -> `/blog`
+does **not** produce `/old-blog` -> `/blog` -> `/news`. It produces
+`/old-blog` -> `/blog`, and `/blog` -> `/news` is gone for good. Never describe
+the result as a chain, a hop, or a redirect sequence.
+
+## Run this check before every create
+
+Do not skip it because the user's request was explicit. The user asking for a
+redirect is not the same as the user agreeing to lose a different one.
+
+1. Call **List Redirects**.
+2. Compare the redirect you are about to create against every existing one:
+   - an existing redirect whose `from` equals your new `to` **will be deleted**
+     (loop resolution, described above);
+   - an existing redirect whose `from` equals your new `from` means your create
+     **fails** with `FROM_URL_EXISTS` and writes nothing.
+   - Paths differing only by a trailing slash count as equal for both checks.
+3. **If either matched, end your turn without writing.** Name the exact redirect
+   at stake and what happens to it, then stop and wait for the user's answer.
+
+   This is a rule about turn structure, not about intent: **never put a create in
+   the same response as the List Redirects that found the conflict.** Reporting
+   the conflict and creating the redirect anyway is the failure this rule exists
+   to prevent - the user cannot answer a question you already acted on. If your
+   next action after listing is a write, you have skipped this step.
+4. If neither matched, no deletion is possible: create it in the same turn and
+   report the result. Do not ask permission you do not need.
+
+`options.forceReplace` is the only way to overwrite a taken `from` path, and it
+**deletes** the redirect holding it. Never set it on your own initiative. Offer it
+only after reporting the conflict, and only if the user asks to replace.
+
+## The six methods and their request shapes
+
+Every path is under `https://www.wixapis.com/seo-redirects-service/v1`. Use these
+directly - do not go looking for the shapes in the docs first.
+
+| Method | Call |
+|---|---|
+| List Redirects | `GET /redirects` - no body, no parameters |
+| Get Redirect | `GET /redirects/{redirectId}` |
+| Create Redirect | `POST /create-redirect` - body below |
+| Delete Redirect | `DELETE /redirects/{redirectId}` - empty response |
+| Bulk Create Redirects | `POST /bulk/redirects/create` |
+| Bulk Delete Redirects | `POST /bulk/redirects/delete` |
+
+Create Redirect takes the redirect nested under `redirect`. `options` and
+`language` are optional, `id` only when preserving an existing redirect's
+identity:
+
+```json
+{
+  "redirect": {
+    "from": "/old-blog",
+    "to": "/blog",
+    "options": { "groupRedirect": true },
+    "language": "fr"
+  }
+}
+```
+
+The two bulk methods take flat lists. Bulk Create's `returnFullEntity` returns
+each created redirect in `results[].item`:
+
+```json
+{ "redirects": [ { "from": "/old-pricing", "to": "/pricing" } ], "returnFullEntity": true }
+```
+
+```json
+{ "redirectIds": ["5b07d9de-6a9f-494d-8066-a7b66c970270"] }
+```
+
+## Worked example: the request that deletes something
+
+The user asks to send `/old-blog` and everything under it to `/blog`.
+
+**1. List first.**
+
+```
+GET https://www.wixapis.com/seo-redirects-service/v1/redirects
+```
+
+```json
+{
+  "redirects": [
+    {
+      "id": "583fe7d7-2944-436f-870a-09eb6d2e52fa",
+      "from": "/blog",
+      "to": "/news",
+      "createdDate": "2026-08-20T09:12:44.000Z"
+    }
+  ]
+}
+```
+
+**2. Compare.** The new `to` is `/blog`, and an existing redirect's `from` is
+`/blog`. That is the deletion case. **End the turn here** - report that creating
+this redirect deletes `/blog` -> `/news` permanently, and that the two will not
+chain, then wait.
+
+**3. Only after the user agrees**, create it:
+
+```
+POST https://www.wixapis.com/seo-redirects-service/v1/create-redirect
+```
+
+```json
+{ "redirect": { "from": "/old-blog", "to": "/blog", "options": { "groupRedirect": true } } }
+```
+
+```json
+{
+  "redirect": {
+    "id": "9c4a1f2e-77b0-4b13-a2c8-6e0d3f5b8a91",
+    "from": "/old-blog",
+    "to": "/blog",
+    "options": { "groupRedirect": true }
+  }
+}
+```
+
+`/blog` -> `/news` is now gone. Say so - do not report it as still in place, and
+do not describe the result as `/old-blog` -> `/blog` -> `/news`.
+
+## When a write fails
+
+Report the failure and stop. Do **not** retry with a different request shape, a
+different path, `forceReplace` added, or a bulk call in place of a single one. A
+failed create wrote nothing, so there is nothing to clean up, and a mutated retry
+is a second attempt at a decision the user has not agreed to.
+
+On the first `403` or `PERMISSION_DENIED`, stop and report the missing
+authorization for managing SEO settings. Do not try another site, path, or method.
+
+## Choose exact or group
+
+| User intent | Setting |
+|---|---|
+| "Redirect this one URL" | omit `options`, or `options.groupRedirect: false` |
+| "Redirect this section", "everything under /blog" | `options.groupRedirect: true` |
+
+A group redirect carries the rest of the URL over to the target: from
+`/forum/questions/` to `/forum/faqs/` sends `/forum/questions/my-post` to
+`/forum/faqs/my-post`. An exact and a group redirect that share a `from` path are
+two different redirects.
+
+For a multilingual site, set `language` to apply the redirect to one language
+only; omit it to apply to every language. A language-scoped path is stored
+**without** the language prefix, so `/fr/about` with `language: "fr"` comes back
+as `/about`. Deleting a language-scoped redirect stops it working but it can
+still appear in List Redirects.
+
+`from` cannot be the site root, and two paths differing only by a trailing slash
+count as the same path.
+
+## Read: List Redirects is the only way to read many
+
+**There is no query endpoint and no search endpoint.** Most Wix APIs have one, so
+this is the second place an agent goes wrong. Do not call, construct, or go
+looking for `POST /v1/redirects/query`, a `/search` path, or any filtered variant:
+they do not exist, and trying one wastes a turn and returns nothing useful.
+
+- **List Redirects** returns every redirect on the site in one response. It takes
+  no filter, sort, cursor, or paging parameter at all. Filter, sort, and slice the
+  returned array yourself. It also returns redirects Wix created for the site
+  owner, such as when a page's URL slug was renamed in the editor.
+- **Get Redirect** retrieves one by ID.
+
+## Change an existing redirect
+
+There is **no update method**, and as above no query method. To change a redirect:
+
+1. Call **Get Redirect** and keep the whole response.
+2. Call **Delete Redirect** with the same ID.
+3. Call **Create Redirect** with every field you retrieved, with your change applied.
+
+Carry the whole redirect across, not only what changed. Create Redirect fills an
+omitted field with its default rather than the previous value, so dropping
+`options` turns a group redirect into an exact one and dropping `language` turns a
+language-scoped redirect into a global one. Keep `id` to preserve the redirect's
+identity, or omit it for a new one.
+
+Confirm with the user before step 2: between the delete and the create the
+redirect is not in effect, and if the create fails the old redirect is gone.
+
+## Batches
+
+**Bulk Create Redirects** and **Bulk Delete Redirects** take 1 to 500 items and
+report each one separately **inside a successful response**:
+
+- Read every outcome from `results[].itemMetadata`, matched to your request by
+  `originalIndex`. A failed item carries `error.code`, such as `FROM_URL_EXISTS`
+  or `REDIRECT_NOT_FOUND`.
+- `bulkActionMetadata.undetailedFailures` counts items whose outcome is
+  **unknown**: they carry no error and may or may not have been written. Call
+  List Redirects to find out. Never report them as successes.
+- A malformed request, such as an empty list, is rejected as a whole with a 400
+  and returns no per-item results.
+
+Two more sharp edges to report truthfully:
+
+- A successful **Bulk Delete** item means the deletion was found and sent, not
+  confirmed. Call List Redirects if the user needs confirmation.
+- Bulk Create is **not atomic**. If an item's conflicting or loop-causing
+  redirect is deleted and the write then fails, the deleted redirect is gone and
+  nothing replaces it. Repeating the same request recreates it.
+
+Creating a redirect identical to one already on the site changes nothing and
+succeeds: Create Redirect echoes the request back without an `id` or
+`createdDate`, and Bulk Create reports success with no `id`. Do not present that
+as a newly created redirect.
+
+## Reading errors
+
+- On a 400, read `details.validationError.fieldViolations` and report the named
+  field rather than guessing.
+- **Known divergence:** the reference documents `REDIRECT_NOT_FOUND` for an
+  unknown redirect ID on Get Redirect and Delete Redirect. The API currently
+  returns a generic 404 without that code. Treat any 404 on those two methods as
+  "no redirect with that ID", and do not tell the user the ID was valid.
+- No webhook or event is emitted when a redirect is created or deleted. Never
+  treat the absence of an event as the absence of a change.

package/skills/wix-manage/references/sites/query-sites.md

@@ -1,173 +1,58 @@
 ---
 name: "Query Sites"
-description: Lists and queries all sites associated with a Wix account using the Sites API. Covers filtering, sorting, and cursor-based pagination.
+description: List, count, and find the sites in a Wix account. Covers the namespace filter for headless sites, counting before enumerating, cursor pagination, and resolving a site by name.
 ---
 # Query Sites
 
-This recipe demonstrates how to list and query the sites associated with a Wix account.
+List, count, and find the sites in a Wix account.
 
-## Prerequisites
+- **Auth**: account-level (a Wix user token, or an account-level API key). `wix token` prints one.
+- **Permission**: `SITE_LIST.READ` (scope `SCOPE.ACC-DC-OS.READ-SITE`).
+- **Endpoints**: list `POST https://www.wixapis.com/site-list/v2/sites/query` · count
+  `POST https://www.wixapis.com/site-list/v2/sites/count`.
 
-- Account-level API access (authenticated as a Wix user or using an account-level API key)
-- Permission `SITE_LIST.READ` (scope `SCOPE.ACC-DC-OS.READ-SITE`)
+## Include headless sites — filter by `namespace`
 
-## Required APIs
+Both endpoints see only `WIX`-namespace sites by default; **headless sites** (anything built on a
+connected OAuth app) are silently excluded. Filter on both namespaces to see everything:
 
-- **Query Sites API**: [REST](https://dev.wix.com/docs/api-reference/account-level/sites/sites/query-sites)
-
-> Returns up to **100** sites per request. Use cursor paging (below) to retrieve more.
-
----
-
-## Query Sites
-
-**Endpoint**: `POST https://www.wixapis.com/site-list/v2/sites/query`
-
-The request takes a `query` object that supports `filter`, `sort`, and `cursorPaging`.
-
-**Request Body**:
-```json
-{
-  "query": {
-    "filter": { "editorType": "EDITOR" },
-    "sort": [{ "fieldName": "createdDate", "order": "ASC" }],
-    "cursorPaging": { "limit": 50 }
-  }
-}
-```
-
-All three fields are optional — `{ "query": { "cursorPaging": { "limit": 50 } } }` lists every site.
-
-**Request**:
 ```bash
-curl -X POST \
-  'https://www.wixapis.com/site-list/v2/sites/query' \
-  -H 'Authorization: <AUTH>' \
-  -H 'Content-Type: application/json' \
-  -d '{
-    "query": {
-      "filter": { "editorType": "EDITOR" },
-      "sort": [{ "fieldName": "createdDate", "order": "ASC" }],
-      "cursorPaging": { "limit": 50 }
-    }
-  }'
-```
-
----
-
-## Response Structure
-
-The response has the sites array plus **two** paging objects: a top-level `cursorPaging`
-(echoes the applied limit and the next cursor) and `metadata` (count, `cursors.next`, `hasNext`).
-
-> ⚠️ There is **no** `pagingMetadata` field. Read paging info from `metadata`.
-
-```json
-{
-  "sites": [
-    {
-      "id": "f6061c5f-6aa3-42f8-8822-36a4981dabb2",
-      "htmlAppId": "70df538d-906c-44ca-9f27-c186b62f2b2b",
-      "name": "my-site-47",
-      "displayName": "My Site 47",
-      "createdDate": "2023-02-01T14:56:09.831Z",
-      "updatedDate": "2026-06-22T03:55:49.031Z",
-      "published": true,
-      "premium": false,
-      "viewUrl": "https://username.wixsite.com/my-site-47",
-      "editUrl": "/editor/f6061c5f-6aa3-42f8-8822-36a4981dabb2?editorSessionId=...",
-      "thumbnail": "/site-thumbnail/f6061c5f-6aa3-42f8-8822-36a4981dabb2",
-      "ownerAccountId": "e6a89eda-d100-4b2d-8a47-3040e2134497",
-      "contributorAccountIds": [],
-      "editorType": "EDITOR",
-      "blocked": false,
-      "namespace": "WIX",
-      "domainConnected": false,
-      "parentChildRole": "NONE"
-    }
-  ],
-  "cursorPaging": {
-    "limit": 50,
-    "cursor": "<cursor-for-next-page>"
-  },
-  "metadata": {
-    "count": 50,
-    "cursors": {
-      "next": "<cursor-for-next-page>"
-    },
-    "hasNext": true
-  }
-}
+curl -X POST 'https://www.wixapis.com/site-list/v2/sites/query' \
+  -H 'Authorization: <ACCOUNT_TOKEN>' -H 'Content-Type: application/json' \
+  -d '{ "query": { "filter": { "namespace": { "$in": ["WIX", "HEADLESS"] } }, "cursorPaging": { "limit": 100 } } }'
 ```
 
-### Site object fields
-
-Each entry in `sites` has these fields (from the `Site` schema):
-
-| Field | Type | Notes |
-|---|---|---|
-| `id` | string | Site ID — use for site-level API calls |
-| `htmlAppId` | string | Internal HTML app ID |
-| `name` | string | URL slug / internal name |
-| `displayName` | string | Human-readable site name |
-| `createdDate` / `updatedDate` | datetime | |
-| `trashedDate` | datetime | Present only if the site is in the trash |
-| `published` | boolean | Whether the site is published |
-| `premium` | boolean | Whether the site has a Wix Premium (paid) plan |
-| `viewUrl` | string | Public site address; empty string when unpublished. **There is no `siteUrl` field.** |
-| `editUrl` | string | Relative editor path; prefix with `https://manage.wix.com` to open |
-| `thumbnail` | string | Relative thumbnail path |
-| `ownerAccountId` | string | |
-| `contributorAccountIds` | string[] | |
-| `editorType` | string | e.g. `EDITOR`, `ODEDITOR` — also a valid `filter` field |
-| `blocked` | boolean | |
-| `folderId` / `parentId` | string | Set for sites organized in folders / parent-child setups |
-| `namespace` | string | e.g. `WIX` |
-| `domainConnected` | boolean | |
-| `parentChildRole` | string | e.g. `NONE` |
+`query` takes optional `filter`, `sort` (e.g. `[{ "fieldName": "createdDate", "order": "DESC" }]`),
+and `cursorPaging` (max `limit` 100).
 
----
+## Count before you enumerate
 
-## Pagination
+An account can hold thousands of sites. To find one by name, search (see "Find a site by name")
+rather than enumerate. To walk the whole list, count first and decide whether that's worth it:
 
-Cursor-based. Read the next cursor from `metadata.cursors.next` and stop when
-`metadata.hasNext` is `false`.
+```bash
+curl -X POST 'https://www.wixapis.com/site-list/v2/sites/count' \
+  -H 'Authorization: <ACCOUNT_TOKEN>' -H 'Content-Type: application/json' \
+  -d '{ "filter": { "namespace": { "$in": ["WIX", "HEADLESS"] } } }'   # → { "count": 1335 }
+```
 
-> The cursor does **not** carry the page limit, and it already encodes the filter/sort
-> from the first request. On follow-up pages send **only** the cursor (plus `limit` if you
-> want a non-default page size) — do **not** repeat `filter` or `sort`.
+Enumerating costs **~0.7s per 100 sites** (100 → ~0.7s, 500 → ~3.4s, ~1,300 → ~9s). For a large
+count, render the first N sites with a "…and N more" note instead of fetching all of them.
 
-**First request**:
-```json
-{
-  "query": {
-    "filter": { "editorType": "EDITOR" },
-    "sort": [{ "fieldName": "createdDate", "order": "ASC" }],
-    "cursorPaging": { "limit": 50 }
-  }
-}
-```
+## Paginate
 
-**Next page** (cursor from `metadata.cursors.next`):
-```json
-{
-  "query": {
-    "cursorPaging": {
-      "limit": 50,
-      "cursor": "<metadata.cursors.next from previous response>"
-    }
-  }
-}
-```
+The next cursor is at `metadata.cursors.next` (there is **no** `pagingMetadata` field); it already
+encodes the filter/sort, so follow-up pages send only the cursor:
 
-**Loop**:
 ```javascript
-async function listAllSites() {
+async function listAllSites(wixPost) {
   const sites = [];
   let cursor = null;
   do {
-    const cursorPaging = cursor ? { limit: 100, cursor } : { limit: 100 };
-    const res = await wixRequest({ query: { cursorPaging } }); // POST .../site-list/v2/sites/query
+    const query = cursor
+      ? { cursorPaging: { limit: 100, cursor } }
+      : { filter: { namespace: { $in: ["WIX", "HEADLESS"] } }, cursorPaging: { limit: 100 } };
+    const res = await wixPost("/site-list/v2/sites/query", { query });
     sites.push(...res.sites);
     cursor = res.metadata.hasNext ? res.metadata.cursors.next : null;
   } while (cursor);
@@ -175,23 +60,49 @@ async function listAllSites() {
 }
 ```
 
----
-
-## Common Use Cases
+## Find a site by name
 
-### List all sites
-Omit `filter` and page through with `cursorPaging` until `metadata.hasNext` is `false`.
+Substring-search by display name with `GET manage.wix.com/account/sites/api/sites/search`. It
+returns full site records (headless included) and, with `getCount=true`, the total:
 
-### Find a specific site
-Prefer server-side `filter` (e.g. `{ "editorType": "EDITOR" }`) and `sort` over fetching
-everything and filtering client-side. Filterable fields match the site object (e.g. `name`,
-`displayName`, `editorType`, `published`).
+```bash
+curl 'https://manage.wix.com/account/sites/api/sites/search?query=kintsugi&getCount=true' \
+  -H 'Authorization: <ACCOUNT_TOKEN>' -H 'accept: application/json'
+# → { "sites": [ { "metaSiteId", "displayName", "namespace", "published", "editUrl", … } ], "totalCount": 5 }
+```
 
----
+## Response — the `Site` object
+
+`sites` is an array of:
+
+```typescript
+interface Site {
+  id: string;                 // site ID — use for site-level API calls
+  htmlAppId: string;
+  name: string;               // URL slug / internal name; opaque `headless-<id>` for headless sites
+  displayName: string;        // human-readable name
+  createdDate: string;        // ISO datetime
+  updatedDate: string;        // ISO datetime
+  trashedDate?: string;       // present only when the site is in the trash
+  published: boolean;
+  premium: boolean;           // has a Wix Premium (paid) plan
+  viewUrl: string;            // public address; "" when unpublished (there is no `siteUrl` field)
+  editUrl: string;            // relative; prefix with https://manage.wix.com to open
+  thumbnail: string;
+  ownerAccountId: string;
+  contributorAccountIds: string[];
+  editorType: string;         // EDITOR | ODEDITOR | STUDIO | EDITORLESS
+  blocked: boolean;
+  folderId?: string;          // set for sites organized in folders / parent-child setups
+  namespace: string;          // WIX | HEADLESS
+  domainConnected: boolean;
+  parentChildRole: string;    // e.g. NONE
+}
+```
 
 ## Next Steps
 
-After finding a site:
-- Use the site `id` for site-level API calls
-- Create new sites using [Create Site from Template](create-site-from-template.md)
-- Manage site settings and content
+Use a site's `id` for site-level API calls — derive a site token from the account token
+(`wix token --site <id>`, or the `oauth2/token` refresh-grant in wix-auth `device-flow`), then read
+its context via [Read Site Context](read-site-context.md) or create sites with
+[Create Site from Template](create-site-from-template.md).

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.