@wix/agent-skills 1.15.0 → 1.16.0

package/skills/wix-manage/references/events/create-wix-event.md

@@ -0,0 +1,176 @@
+---
+name: "Create an Event with the Wix Events API"
+description: "Creates an event with the Wix Events V3 API — the required request body, ISO-8601 date and time settings, venue/online/TBD location, RSVP vs ticketed registration, guest capacity, and short vs rich-text descriptions. Covers the exact field shapes and the API's misleading validation messages. Use when the user wants to create an event, set its date, location, description or guest limit, or choose between RSVP and ticketing."
+---
+
+# Create an Event with the Wix Events API
+
+## Goal
+Create an event on a Wix site — one-off or recurring, RSVP or ticketed — with the Wix Events
+V3 API. To publish, cancel, clone, count, add tickets or set up a recurring series, see
+[Manage Wix Events](manage-wix-events.md).
+
+## First: pick the right "Events" API
+
+Several unrelated Wix APIs are called "Events". Routing to the wrong one is the most expensive
+mistake on this surface, because the wrong API answers plausibly for several calls before
+failing.
+
+| The user means | API | Base path |
+| --- | --- | --- |
+| A public event guests attend — gala, concert, workshop, meetup | **Wix Events V3** — this recipe | `/events/v3/events` |
+| A bookable session on a staff or service calendar | Calendar Events V3 | `/calendar/v3/events` |
+| An entry on the marketing plan calendar | Marketing Calendar Event V1 | `/promote/marketing-plan-service/v1/events` |
+| An automation trigger | Triggered Events | `/automations/v1/events/report` |
+
+A recurring *class or course that guests book* is Bookings, not Wix Events. A recurring
+*event series guests attend* is Wix Events.
+
+## Prerequisite — the Wix Events app must be installed
+
+Every `/events/v3` call against a site without the app returns:
+
+```
+428  {"message":"Events app not installed for metaSiteId=...",
+      "details":{"applicationError":{"code":"WIX_EVENTS_APP_NOT_INSTALLED"}}}
+```
+
+Install it with appDefId `140603ad-af8d-84a5-2c80-a0f60cb47351` — see
+[Install Wix Apps](../app-installation/install-wix-apps.md). Confirm with the user first unless
+they already asked for the event to be created.
+
+## Create the event
+
+```bash
+curl -X POST 'https://www.wixapis.com/events/v3/events' \
+  -H 'Content-Type: application/json' \
+  -H 'Authorization: <AUTH>' \
+  --data-binary '{
+    "event": {
+      "title": "Summer Gala",
+      "location": { "name": "Grand Hall", "type": "VENUE" },
+      "dateAndTimeSettings": {
+        "startDate": "2026-09-15T19:00:00.000Z",
+        "endDate": "2026-09-15T22:00:00.000Z",
+        "timeZoneId": "America/New_York"
+      },
+      "registration": { "initialType": "RSVP" }
+    },
+    "draft": true
+  }'
+```
+
+`title`, `location`, `dateAndTimeSettings` and `registration.initialType` are all required.
+Drop `"draft": true` to create the event already published; a draft has `status: "DRAFT"` and
+is invisible on the site until published with `POST /events/v3/events/{eventId}/publish`
+(empty body), which moves it to `UPCOMING`.
+
+## Date and time
+
+**`startDate` and `endDate` are ISO-8601 strings, not `{seconds, nanos}` objects.**
+
+The spec types these fields as `string` / `format: date-time` but also carries a pointer to the
+`google.protobuf.Timestamp` message, whose fields are `seconds` and `nanos`. That message
+describes the *internal* representation and must not be sent — it fails with
+`400 {"message":"Expected a string."}`. This applies to every date-time field across the Wix
+APIs, not only Events.
+
+| Rule | If broken |
+| --- | --- |
+| `startDate` / `endDate` are ISO-8601 strings | `400 Expected a string.` |
+| `endDate` is required | `400 endDate.isDefined must be true, event cannot have negative duration` |
+| `timeZoneId` is required, in [TZ database](https://www.iana.org/time-zones) form (`America/New_York`) | `400 getTimeZoneId is not supported` |
+
+> The `timeZoneId` error reads as though the field is unsupported. It is not — it means the
+> field is **missing**. Add `timeZoneId`; do not remove it.
+
+**Date to be announced:** send `dateAndTimeSettings` as
+`{ "dateAndTimeTbd": true, "dateAndTimeTbdMessage": "Date coming soon" }` and nothing else. The
+message is mandatory — omitting it fails with `400 getScheduleTbdMessage must not be a blank`.
+
+## Location
+
+`location.type` is `VENUE` or `ONLINE`. There is no `TBD` type — a to-be-announced location is
+a `VENUE` with `locationTbd: true`.
+
+| Body | Result |
+| --- | --- |
+| `{ "name": "Grand Hall", "type": "VENUE" }` | Accepted |
+| `{ "name": "Zoom", "type": "ONLINE" }` | Accepted |
+| `{ "name": "To be announced", "locationTbd": true }` | Accepted — `type` defaults to `VENUE` |
+| `{ "locationTbd": true }` | `400 Event location is invalid ... Location address must not be a blank` |
+| `{ "name": "TBA", "type": "TBD", "locationTbd": true }` | `400 type enum must be in [VENUE(0), ONLINE(1)]` |
+
+For a real street address, add an `address` object:
+
+```json
+"location": {
+  "name": "Javits Center", "type": "VENUE",
+  "address": {
+    "country": "US", "subdivision": "US-NY", "city": "New York", "postalCode": "10001",
+    "streetAddress": { "number": "429", "name": "11th Ave" }
+  }
+}
+```
+
+`subdivision` is the ISO-3166-2 code (`US-NY`), and the API fills in `formattedAddress` and
+`geocode` on the response. A `VENUE` with no `address` comes back with `locationTbd: true` set
+by the API whether or not you sent it.
+
+## Registration type and capacity
+
+`initialType` must be nested under `registration`; at the root of `event` it is treated as
+omitted and fails with the same error. Accepted values are **`RSVP`**, **`TICKETING`**,
+`EXTERNAL` and `NONE`.
+
+> The API's error text for this field advertises `[RSVP,TICKETS,RSVP_AND_TICKETS]`. Those
+> values do not work — `TICKETS` is rejected. Use `TICKETING`.
+
+`initialType` is immutable: an `RSVP` event can never become a `TICKETING` event or vice versa
+(either can later become `EXTERNAL` or `NONE` via `registration.type`). Choose correctly at
+creation time — "people should register by RSVP, not tickets" means `RSVP`.
+
+**Guest limit.** For an RSVP event, the cap is `registration.rsvp.limit`:
+
+```json
+"registration": { "initialType": "RSVP", "rsvp": { "limit": 30 } }
+```
+
+A `limit` placed directly on `registration` is **silently ignored** — the event is created with
+no cap and no error. Set `waitlistEnabled: true` alongside it to let guests join a waitlist once
+the limit is reached. For a ticketed event the cap is per ticket type, via `initialLimit` on the
+ticket definition — see [Manage Wix Events](manage-wix-events.md).
+
+## Description — two different fields
+
+| Field | Type | Use for |
+| --- | --- | --- |
+| `shortDescription` | plain string, max 500 | A one-line description under the event title |
+| `description` | Ricos rich content object | The formatted body on the event page |
+
+A plain sentence belongs in `shortDescription`. Sending a string to `description` fails with
+`400 {"message":"Expected an object"}` — it takes a Ricos `{ "nodes": [...] }` tree, as built in
+[Rich Content](../rich-content/author-ricos-rich-content.md):
+
+```json
+"description": { "nodes": [ { "type": "PARAGRAPH", "id": "p1", "paragraphData": {},
+  "nodes": [ { "type": "TEXT", "id": "", "nodes": [],
+               "textData": { "text": "Monthly meetup to discuss a new book.", "decorations": [] } } ] } ] }
+```
+
+`shortDescription` is only returned when the request asks for `"fields": ["DETAILS"]`, and
+`description` only with `"fields": ["TEXTS"]`. Both are stored regardless.
+
+## Gotchas & troubleshooting
+
+- **An invalid enum value reports as a missing one.** Sending a value outside an enum returns
+  `<field> value is required` rather than "invalid value". If a field you *did* send is reported
+  as required, suspect the value, not its presence.
+- **Error text names internal accessors, not request fields.** `getTimeZoneId`,
+  `getScheduleTbdMessage` and `endDate.isDefined` each map to the plain field of the same name.
+- `title` is required, min 1 and max 120 characters. There is no separate name field.
+
+## Related APIs
+- **Wix Events V3**: [REST](https://dev.wix.com/docs/api-reference/business-solutions/events/event-management/events-v3)
+- [Manage Wix Events](manage-wix-events.md) — tickets, publish, cancel, clone, recurring, count
+- [Install Wix Apps](../app-installation/install-wix-apps.md) — the `428` pre-flight

package/skills/wix-manage/references/events/manage-wix-events.md

@@ -0,0 +1,174 @@
+---
+name: "Manage Wix Events — Tickets, Publishing, Cloning and Recurring Series"
+description: "Manages existing events with the Wix Events V3 API — ticket definitions and pricing (fixed price, free, donation, multiple tiers), publishing a draft, cancelling, deleting, cloning, updating an event's date or details, counting events, and creating a recurring series. Use when the user wants to add or price tickets, publish or cancel an event, duplicate an event, move an event's date, count their events, or set up a repeating event."
+---
+
+# Manage Wix Events — Tickets, Publishing, Cloning and Recurring Series
+
+## Goal
+Operate on events that already exist: sell tickets, publish, cancel, delete, clone, update,
+count, and build recurring series. To create the event in the first place — including its date,
+location, description and guest limit — see [Create an Event](create-wix-event.md).
+
+## Prerequisite — the Wix Events app must be installed
+
+Every endpoint here returns `428 WIX_EVENTS_APP_NOT_INSTALLED` against a site without the app.
+Install it first — do not guess the install path, which is easy to get wrong:
+
+```bash
+curl -X POST 'https://www.wixapis.com/apps-installer-service/v1/app-instance/install' \
+  -H 'Content-Type: application/json' \
+  -H 'Authorization: <AUTH>' \
+  --data-binary '{
+    "tenant": { "tenantType": "SITE", "id": "<SITE_ID>" },
+    "appInstance": { "appDefId": "140603ad-af8d-84a5-2c80-a0f60cb47351" }
+  }'
+```
+
+`appDefId` nests under `appInstance`, not at the root — at the root it fails with
+`400 appInstance must not be empty`. See [Install Wix Apps](../app-installation/install-wix-apps.md)
+for the full flow.
+
+## Ticket definitions
+
+Ticket definitions belong to events created with `"initialType": "TICKETING"`. Tickets are a
+separate API; up to 100 definitions per event.
+
+```bash
+curl -X POST 'https://www.wixapis.com/events/v3/ticket-definitions' \
+  -H 'Content-Type: application/json' \
+  -H 'Authorization: <AUTH>' \
+  --data-binary '{
+    "ticketDefinition": {
+      "eventId": "<EVENT_ID>",
+      "name": "General Admission",
+      "pricingMethod": { "fixedPrice": { "value": "25.00", "currency": "USD" } },
+      "feeType": "FEE_ADDED_AT_CHECKOUT",
+      "initialLimit": 100
+    }
+  }'
+```
+
+| To create | `pricingMethod` |
+| --- | --- |
+| A fixed-price ticket | `{ "fixedPrice": { "value": "25.00", "currency": "USD" } }` |
+| A free ticket | `{ "fixedPrice": { "value": "0", "currency": "USD" } }` |
+| A donation / pay-what-you-want ticket, with a minimum | `{ "guestPrice": { "value": "5.00", "currency": "USD" } }` |
+
+Easy to get wrong:
+
+- **`feeType` is required** — `FEE_ADDED_AT_CHECKOUT` (fee on top of the price) or
+  `FEE_INCLUDED` (fee absorbed into it).
+- **`value` is a string.** `"value": 10` fails with `400 Unexpected value for field value`.
+- **There is no writable `free` flag.** `pricingMethod.free` is read-only, computed from the
+  price; sending `{"free": true}` fails with `value fixedPrice or guestPrice or pricingOptions
+  must not be empty`.
+- **The quantity field is `initialLimit`**, not `initialQuantity`. Omit it for unlimited tickets.
+- `limitPerCheckout` is read-only — it cannot be set on create.
+- `name` is capped at 30 characters, `description` at 500.
+
+**Multiple tiers** — call the endpoint once per tier with the same `eventId`. For "General
+Admission at $20 and VIP at $50", that is two calls, each with its own `name`, `fixedPrice` and
+`initialLimit`. There is no bulk-create for ticket definitions.
+
+## Publish, cancel and delete
+
+| Action | Call | Resulting `status` |
+| --- | --- | --- |
+| Publish a draft | `POST /events/v3/events/{eventId}/publish` | `UPCOMING` |
+| Cancel | `POST /events/v3/events/{eventId}/cancel` | `CANCELED` |
+| Delete | `DELETE /events/v3/events/{eventId}` | — |
+
+Publish and cancel take an empty body. Publishing is irreversible — a published event cannot
+return to `DRAFT`. Cancelling closes registration but keeps the event; deleting removes it.
+
+## Clone an event
+
+`POST /events/v3/events/{eventId}/clone` with an empty body copies the registration form,
+notifications, translations and ticket configuration.
+
+> **The clone does not keep the original's date.** Its start date is reset to roughly 14 days
+> from now, and it comes back as a `DRAFT`. If the user wanted a duplicate on a particular date,
+> follow the clone with an update, then publish it.
+
+## Update an event
+
+`PATCH /events/v3/events/{event.id}` with the fields to change nested under `event`:
+
+```bash
+curl -X PATCH 'https://www.wixapis.com/events/v3/events/<EVENT_ID>' \
+  -H 'Content-Type: application/json' \
+  -H 'Authorization: <AUTH>' \
+  --data-binary '{
+    "event": {
+      "dateAndTimeSettings": {
+        "startDate": "2026-10-15T19:00:00.000Z",
+        "endDate": "2026-10-15T22:00:00.000Z",
+        "timeZoneId": "America/New_York"
+      }
+    }
+  }'
+```
+
+The Events API takes **no field mask and no `revision`** on update — send only the fields you
+are changing. Send `dateAndTimeSettings` complete when moving a date: `startDate`, `endDate` and
+`timeZoneId` together, since the same required-field rules apply as on create.
+
+Ticket definitions are the exception — `PATCH /events/v3/ticket-definitions/{ticketDefinition.id}`
+*does* require the current `revision`, which increments on every update.
+
+## Count events
+
+`POST /events/v3/events/query` and read `pagingMetadata.total`:
+
+```json
+{ "query": { "paging": { "limit": 100 } } }
+```
+
+Query Events returns only published events — **drafts are excluded from both the results and the
+total**. Create with `"draft": false`, or publish first, if the count is meant to include the
+event you just made.
+
+`POST /events/v3/events/count-by-status` exists, but an empty request body returns empty `facets`
+even when the site has events, so it is not the way to answer "how many events do I have".
+
+## Recurring events
+
+Wix Events has **no recurrence rule** — no `RRULE`, no "weekly" pattern. Calculate every
+occurrence date yourself and list them all (up to 1000), alongside the normal top-level
+`startDate` / `endDate` / `timeZoneId`:
+
+```json
+"dateAndTimeSettings": {
+  "startDate": "2026-10-20T18:00:00.000Z",
+  "endDate": "2026-10-20T19:00:00.000Z",
+  "timeZoneId": "America/New_York",
+  "recurringEvents": {
+    "individualEventDates": [
+      { "startDate": "2026-10-20T18:00:00.000Z", "endDate": "2026-10-20T19:00:00.000Z", "timeZoneId": "America/New_York" },
+      { "startDate": "2026-10-27T18:00:00.000Z", "endDate": "2026-10-27T19:00:00.000Z", "timeZoneId": "America/New_York" }
+    ]
+  }
+}
+```
+
+For "a weekly event starting next week", generate the dates yourself — pick a sensible horizon
+(a few months) and say how many occurrences you created. The event returns
+`recurrenceStatus: "RECURRING"`. Each occurrence is an independent event with its own ID,
+updatable and deletable on its own; all share a generated `recurringEvents.categoryId`. Query by
+that `categoryId` to retrieve the whole series.
+
+## Gotchas & troubleshooting
+
+- **An invalid enum value reports as a missing one.** A value outside an enum returns
+  `<field> value is required` rather than "invalid value" — true for `feeType` and
+  `registration.initialType`. If a field you *did* send is reported as required, suspect the
+  value, not its presence.
+- Dates are always ISO-8601 strings, never `{seconds, nanos}` — see
+  [Create an Event](create-wix-event.md).
+
+## Related APIs
+- **Wix Events V3**: [REST](https://dev.wix.com/docs/api-reference/business-solutions/events/event-management/events-v3)
+- **Ticket Definitions V3**: [REST](https://dev.wix.com/docs/api-reference/business-solutions/events/event-management/ticket-definitions-v3)
+- **Event Guests**: `POST /events/v2/guests/query` — who registered
+- [Create an Event](create-wix-event.md) — the create body, dates, location, capacity

package/skills/wix-manage/references/forms/forms-dashboard-navigation.md

@@ -0,0 +1,44 @@
+---
+name: "Forms Dashboard Navigation"
+description: "Builds direct links to Wix Forms dashboard pages on manage.wix.com — the forms list, the submissions table, the form builder for a specific form, standalone forms, templates, and forms settings. Pairs each main Forms entity (form, submission) with its read API so you can fetch an entity and hand back a 'view it in your dashboard' link. Use when the user asks where something is in the Wix dashboard, wants a direct link to a dashboard page, or you need a dashboard URL to include with the result of an API operation."
+---
+
+# Forms Dashboard Navigation
+
+Build direct links into the Wix Forms pages of a site's dashboard. For the general URL contract (metaSiteId, fallbacks, redirects), see [Dashboard Navigation](../dashboard-navigation/dashboard-navigation.md).
+
+## Main Pages
+
+| Page | URL after `/dashboard/{metaSiteId}/` | What it manages |
+|---|---|---|
+| Forms list | `wix-forms` | All forms on the site |
+| Form builder | `wix-forms/form/{formId}` | Edit a specific form (fields, rules, submit settings) |
+| Standalone form | `wix-forms/standalone-form` | Create a standalone form (has its own shareable page, not embedded in a site page) |
+| Submissions | `wix-forms-and-payments/submissions` | Submissions table across forms |
+| Templates | `wix-forms-and-payments/templates` | Create a form from a template |
+| Forms settings | `wix-forms-and-payments/settings` | Forms-level settings |
+
+Two URL namespaces appear here because the forms management pages and the form builder are registered by two apps (`14ce1214-b278-a7e4-1373-00cebd1bef7c` and `225dd912-7dea-4738-8688-4b8c6955ffc2`); `wix-forms` also redirects to the forms list, so it's the stable entry point.
+
+Entity-specific links (`{formId}`) accept the entity's ID appended as an extra path segment. Query params can follow.
+
+## Pairing Entities with Their Read APIs
+
+Fetch the entity via REST, then link the matching dashboard page. All calls use `https://www.wixapis.com` with an `Authorization` header. Dashboard forms use the `wix.form_app.form` namespace.
+
+| Entity | Read API | Dashboard link |
+|---|---|---|
+| Form | `GET /form-schema-service/v4/forms` · `POST /form-schema-service/v4/forms/query` · `GET /form-schema-service/v4/forms/{formId}` | `wix-forms/form/{formId}` (edit) or `wix-forms` (list) |
+| Submission | `POST /form-submission/v4/submissions/namespace/query` (filter must include the `namespace`) · `GET /form-submission/v4/submissions/{submissionId}` | `wix-forms-and-payments/submissions` |
+
+Example — after creating a form, hand back its links:
+
+```
+Created "Contact Form".
+Edit it here: https://manage.wix.com/dashboard/{metaSiteId}/wix-forms/form/{formId}
+See submissions: https://manage.wix.com/dashboard/{metaSiteId}/wix-forms-and-payments/submissions
+```
+
+## Notes
+
+- Creating forms via the [Create Form](./create-form.md) recipe (Form Schemas API) makes them appear in the forms list above.

package/skills/wix-manage/references/get-paid/get-paid-dashboard-navigation.md

@@ -0,0 +1,52 @@
+---
+name: "Get Paid Dashboard Navigation"
+description: "Builds direct links to Wix payments and invoicing dashboard pages on manage.wix.com — payment links, invoices (list, create, settings), recurring invoices, and the accept-payments settings page. Pairs each main get-paid entity with its read API so you can fetch an entity and hand back a 'view it in your dashboard' link. Use when the user asks where something is in the Wix dashboard, wants a direct link to a dashboard page, or you need a dashboard URL to include with the result of an API operation."
+---
+
+# Get Paid Dashboard Navigation
+
+Build direct links into the payments and invoicing pages of a site's dashboard. For the general URL contract (metaSiteId, fallbacks, redirects), see [Dashboard Navigation](../dashboard-navigation/dashboard-navigation.md).
+
+Get-paid pages are split across **four apps** with four URL namespaces:
+
+- **Pay Links** (`324cf725-53d9-4bb2-b8f6-0c8ec9a77f45`) — payment links. Routes under `pay-links/`.
+- **Wix Invoices** (`13ee94c1-b635-8505-3391-97919052c16f`) — invoices and price quotes. Routes under `wix-invoices/`.
+- **Recurring Invoices** (`35aec784-bbec-4e6e-abcb-d3d724af52cf`) — subscription invoices. Routes under `recurring-invoices/`.
+- **Payments** (`14bca956-e09f-f4d6-14d7-466cb3f09103`) — the accept-payments settings. Routes under `wix-cashier/`.
+
+## Main Pages
+
+| Page | URL after `/dashboard/{metaSiteId}/` | What it manages |
+|---|---|---|
+| Payment links | `pay-links` | All payment links |
+| Invoices list | `wix-invoices` | All invoices |
+| New invoice | `wix-invoices/invoice/new` | Create an invoice |
+| Invoice items & services | `wix-invoices/products/list` | Reusable line items for invoices |
+| Invoice reports | `wix-invoices/reports` | Revenue / tax summaries |
+| Invoices settings | `wix-invoices/settings` | Numbering, customization, automations, pay links, price quotes |
+| Recurring invoices | `recurring-invoices` | Subscription invoices list |
+| New recurring invoice | `recurring-invoices/form` | Create a recurring invoice |
+| Accept payments | `wix-cashier/payments` | Payment methods and provider settings |
+
+Older links (`payment-links`, `invoices`, `invoices/create`, `payments`) redirect to the current routes.
+
+## Pairing Entities with Their Read APIs
+
+Fetch the entity via REST, then link the matching dashboard page. All calls use `https://www.wixapis.com` with an `Authorization` header.
+
+| Entity | Read API | Dashboard link |
+|---|---|---|
+| Payment link | `POST /payment-links/v1/payment-links/query` · `GET /payment-links/v1/payment-links/{paymentLinkId}` | `pay-links` |
+| Invoice | Invoices API (Query Invoices) | `wix-invoices` |
+| Payment provider setup | Wix Payments Account API (`POST /payments/v1/wix-payments-account/connect` for onboarding status) | `wix-cashier/payments` |
+
+Example — after creating a payment link:
+
+```
+Created a $50 payment link for "Consultation".
+Manage your payment links here: https://manage.wix.com/dashboard/{metaSiteId}/pay-links
+```
+
+## Notes
+
+- Wix Payments account-level pages (payouts, balance, disputes) are part of the provider's own dashboard flow and aren't stable site-dashboard routes — link `wix-cashier/payments` for anything payment-provider related.

package/skills/wix-manage/references/get-paid/how-to-setup-wix-payments.md

@@ -10,12 +10,19 @@ This recipe covers the setup flow needed before creating payment links or collec
 
 Before connecting Wix Payments, collect and confirm:
 
-1. Terms acceptance: https://www.wix.com/about/terms-of-payments
+1. Terms acceptance: https://support.wix.com/en/article/wix-payments-terms-of-service
 2. First name
 3. Last name
 4. Product/service description (minimum meaningful business description)
+5. The site's country — if not already known, get it from `properties.locale.country` via `GET https://www.wixapis.com/site-properties/v4/properties`
 
-## Step 2: Connect Wix Payments account
+## Step 2: Check country support
+
+Wix Payments self-serve connect is currently supported for these countries: `US, CA, GB, ES, AT, BE, FI, DE, IT, NL, PT, CH, LT`.
+
+If the site's country is not on this list, stop here — do not call connect. Tell the user self-serve connect isn't available yet for their country, and point them to the dashboard instead (Settings → Accept Payments).
+
+## Step 3: Connect Wix Payments account
 
 Call:
 
@@ -27,12 +34,13 @@ Call:
     "firstName": "<USER_FIRST_NAME>",
     "lastName": "<USER_LAST_NAME>",
     "tosAccepted": true,
-    "productDescription": "<PRODUCT_DESCRIPTION>"
+    "productDescription": "<PRODUCT_DESCRIPTION>",
+    "country": "<COUNTRY_CODE verified in Step 2>"
   }
 }
 ```
 
-## Step 3: Handle common setup blockers
+## Step 4: Handle common setup blockers
 
 ### Location-related failure
 
@@ -43,15 +51,30 @@ If setup fails due to location details, update the business location and retry:
 
 ### Already connected
 
-If the API returns an "already connected" style response, skip reconnect and continue with onboarding checks.
+If the account is already connected, the API returns `HTTP 500` with a body like:
+
+```json
+{
+  "message": "payments already connected",
+  "details": { "applicationError": { "code": "INTERNAL_ERROR" } }
+}
+```
+
+Match on the `message` text, not on the `code` alone — `INTERNAL_ERROR` is a generic code reused for unrelated failures too. On this match, skip reconnect and continue with onboarding checks.
 
-## Step 4: Complete dashboard onboarding
+### Unsupported country
+
+If `account.country` isn't one of the countries listed in Step 2, expect an `INVALID_ARGUMENT`-style `HTTP 400` error. Step 2's own check should make hitting this rare — don't retry the call with a different country value; tell the user the same thing Step 2 would have.
+
+## Step 5: Complete dashboard onboarding
 
 Connecting the account is not always the final step. To receive payments, the site owner may still need to complete Wix Payments onboarding in the site dashboard.
 
+Connecting Wix Payments and being able to accept real checkout payments are two separate gates: the site may also need a premium eCommerce plan (Settings → Plans). Mention this even after a successful connect.
+
 ## Important Notes
 
 1. Never invent or assume user identity/business details.
-2. Always obtain explicit user consent before calling connect.
+2. Always obtain explicit user consent before calling connect — this creates a real Wix Payments account and records a legally-binding Terms of Service acceptance under the name provided.
 3. Use the exact accepted values provided by the user.
 4. Verify readiness by testing a real payment flow (for example, create payment link) after setup.

package/skills/wix-manage/references/google-ads/billing-and-payment.md

@@ -0,0 +1,80 @@
+---
+name: "Retrieve Google Ads Billing and Payment Details"
+description: "Retrieves billing and payment details for a Wix site's Google Ads account: the current billing period's ad spend (usage), the Wix service fee, the total charge, any promotional coupon adjustment, the billing period dates, and the account's credit balance (positive = available credits, negative = outstanding debt not yet charged). Also explains reading current vs remaining budget from the account object. Use when the user asks 'how much have I spent on Google Ads', 'what's my next Google Ads charge', 'show my ad billing', 'do I have ad credits left', 'why was I charged', or 'upcoming Google Ads payment'. Requires an existing Google Ads account. REST base https://www.wixapis.com/google-ads/v1."
+---
+# RECIPE: Retrieve Google Ads Billing and Payment Details
+
+Report what a site owner will be charged for Google Ads: ad spend, the Wix service fee, coupon adjustments, the total, the billing period, and the account's credit balance.
+
+Base URL: `https://www.wixapis.com/google-ads/v1`. `<AUTH>` is the `Authorization` header. This endpoint is read-only.
+
+**Prerequisite:** a Google Ads account must exist (`ACCOUNT_NOT_FOUND` → run [install-and-create-account](install-and-create-account.md)).
+
+---
+
+## Get payment details
+
+Billing is calculated from cached subscription data (not fetched live from Google), and the charge calculation is heavy — this endpoint has a **30-second SLA**, so allow time and don't retry prematurely.
+
+```bash
+curl -X GET 'https://www.wixapis.com/google-ads/v1/payment-details' -H 'Authorization: <AUTH>'
+```
+
+```json
+{
+  "paymentDetails": {
+    "currency": "USD",
+    "upcomingPayments": [
+      {
+        "usageAmount": "123.45",
+        "wixServiceFee": "12.35",
+        "totalAmount": "135.80",
+        "billingPeriod": { "from": "2026-03-01", "to": "2026-03-31" },
+        "couponAdjustmentAmount": "0.00"
+      }
+    ],
+    "creditBalance": "0.00"
+  }
+}
+```
+
+**Reading the response:**
+- `currency` — the account's billing currency; all amounts here are in it.
+- `upcomingPayments[]` — the current billing period breakdown (up to 2 entries). Per entry:
+  - `usageAmount` — ad spend for the period, **excluding** the Wix fee.
+  - `wixServiceFee` — the Wix platform fee.
+  - `couponAdjustmentAmount` — discount applied from a promotional coupon.
+  - `totalAmount` — what will actually be charged: `usageAmount + wixServiceFee − couponAdjustmentAmount`.
+  - `billingPeriod` — `from`/`to` dates (YYYY-MM-DD).
+- `creditBalance` — the site's credits. **Positive** = credits available (e.g. from an incentive) that offset upcoming charges; **negative** = outstanding debt not yet charged. The final amount can shift slightly once the charge is processed.
+
+When summarizing for the user, lead with `totalAmount` and the billing period, then break out spend vs fee, and flag a non-zero `creditBalance` (credits remaining, or debt owed).
+
+> Note: an older `monthlyPayments` field is deprecated in favor of `upcomingPayments` — always read `upcomingPayments`.
+
+---
+
+## Budget vs. billing — a related but different view
+
+Payment details cover *charges*. The **account object** (from `GET /v1/accounts/current-site`, see [install-and-create-account](install-and-create-account.md)) carries the *ad-budget* view:
+- `currentBudget` — remaining ad budget/credit (negative = debt not yet charged).
+- `spentBudget` — total spent on ads so far.
+
+Use payment details for "what will I be charged and when"; use the account's budget fields for "how much ad budget is left."
+
+---
+
+## Error handling
+
+| Symptom | Cause | Fix |
+| --- | --- | --- |
+| `NOT_FOUND` / `ACCOUNT_NOT_FOUND` | No Google Ads account for the site | Run [install-and-create-account](install-and-create-account.md) |
+| Slow response (up to ~30s) | Charge calculation SLA | Wait; don't retry prematurely |
+| `upcomingPayments` empty | No charges accrued yet this period | Report zero upcoming charges; check `creditBalance` for credits/debt |
+| Negative `creditBalance` | Outstanding debt not yet charged | Explain it's owed and will be charged; not an error |
+
+## References
+
+- [Payment Details Service introduction](https://dev.wix.com/docs/api-reference/business-management/marketing/ads/google-ads/payment-details-v1/introduction)
+- [Get Payment Details](https://dev.wix.com/docs/api-reference/business-management/marketing/ads/google-ads/payment-details-v1/get-payment-details)
+- [Account Service](https://dev.wix.com/docs/api-reference/business-management/marketing/ads/google-ads/google-account-v1/introduction)