@wix/agent-skills 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (220) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +111 -0
  3. package/package.json +29 -0
  4. package/skills/wix-app/SKILL.md +344 -0
  5. package/skills/wix-app/references/APP_IDENTIFIERS.md +35 -0
  6. package/skills/wix-app/references/APP_MARKET_REVIEW.md +311 -0
  7. package/skills/wix-app/references/APP_VALIDATION.md +171 -0
  8. package/skills/wix-app/references/BACKEND_API.md +233 -0
  9. package/skills/wix-app/references/BACKEND_EVENT.md +116 -0
  10. package/skills/wix-app/references/CODE_QUALITY.md +33 -0
  11. package/skills/wix-app/references/CUSTOM_ELEMENT_WIDGET.md +587 -0
  12. package/skills/wix-app/references/DASHBOARD_MENU_PLUGIN.md +157 -0
  13. package/skills/wix-app/references/DASHBOARD_MODAL.md +283 -0
  14. package/skills/wix-app/references/DASHBOARD_PAGE.md +403 -0
  15. package/skills/wix-app/references/DASHBOARD_PLUGIN.md +205 -0
  16. package/skills/wix-app/references/DATA_COLLECTION.md +451 -0
  17. package/skills/wix-app/references/DOCUMENTATION.md +42 -0
  18. package/skills/wix-app/references/EDITOR_REACT_COMPONENT.md +65 -0
  19. package/skills/wix-app/references/EMBEDDED_SCRIPT.md +468 -0
  20. package/skills/wix-app/references/EXTENSION_REGISTRATION.md +96 -0
  21. package/skills/wix-app/references/SERVICE_PLUGIN.md +235 -0
  22. package/skills/wix-app/references/SITE_PLUGIN.md +436 -0
  23. package/skills/wix-app/references/STORES_VERSIONING.md +334 -0
  24. package/skills/wix-app/references/backend-event/COMMON-EVENTS.md +84 -0
  25. package/skills/wix-app/references/custom-element-widget/SETTINGS_PANEL.md +345 -0
  26. package/skills/wix-app/references/dashboard-menu-plugin/blog-slots.md +71 -0
  27. package/skills/wix-app/references/dashboard-menu-plugin/bookings-slots.md +58 -0
  28. package/skills/wix-app/references/dashboard-menu-plugin/crm-slots.md +8 -0
  29. package/skills/wix-app/references/dashboard-menu-plugin/ecommerce-slots.md +17 -0
  30. package/skills/wix-app/references/dashboard-menu-plugin/events-slots.md +29 -0
  31. package/skills/wix-app/references/dashboard-menu-plugin/restaurants-slots.md +27 -0
  32. package/skills/wix-app/references/dashboard-menu-plugin/stores-slots.md +35 -0
  33. package/skills/wix-app/references/dashboard-page/API_SPEC.md +138 -0
  34. package/skills/wix-app/references/dashboard-page/DASHBOARD_API.md +573 -0
  35. package/skills/wix-app/references/dashboard-page/DYNAMIC_PARAMETERS.md +269 -0
  36. package/skills/wix-app/references/dashboard-page/ECOM_NAVIGATION.md +164 -0
  37. package/skills/wix-app/references/dashboard-plugin/SLOTS.md +294 -0
  38. package/skills/wix-app/references/data-collection/WIX_DATA.md +270 -0
  39. package/skills/wix-app/references/data-collection/extension-template.ts +107 -0
  40. package/skills/wix-app/references/editor-react-component/ACCESSIBILITY.md +138 -0
  41. package/skills/wix-app/references/editor-react-component/COMPONENT-API.md +454 -0
  42. package/skills/wix-app/references/editor-react-component/COMPONENT-CONFIGURATION.md +165 -0
  43. package/skills/wix-app/references/editor-react-component/CSS-GUIDELINES.md +576 -0
  44. package/skills/wix-app/references/editor-react-component/DIRECTIONALITY.md +170 -0
  45. package/skills/wix-app/references/editor-react-component/EDIT-FLOW.md +6 -0
  46. package/skills/wix-app/references/editor-react-component/PARTS.md +25 -0
  47. package/skills/wix-app/references/editor-react-component/PROPS-VS-CSS.md +203 -0
  48. package/skills/wix-app/references/editor-react-component/REACT-GUIDELINES.md +167 -0
  49. package/skills/wix-app/references/editor-react-component/REACT-PATTERNS.md +137 -0
  50. package/skills/wix-app/references/service-plugin/ADDITIONAL-FEES.md +112 -0
  51. package/skills/wix-app/references/service-plugin/BOOKINGS-STAFF-SORTING.md +118 -0
  52. package/skills/wix-app/references/service-plugin/DISCOUNT-TRIGGERS.md +87 -0
  53. package/skills/wix-app/references/service-plugin/GIFT-CARDS.md +86 -0
  54. package/skills/wix-app/references/service-plugin/PAYMENT-SETTINGS.md +135 -0
  55. package/skills/wix-app/references/service-plugin/SHIPPING-RATES.md +79 -0
  56. package/skills/wix-app/references/service-plugin/VALIDATIONS.md +68 -0
  57. package/skills/wix-app/references/site-plugin/EXAMPLES.md +311 -0
  58. package/skills/wix-app/references/site-plugin/SLOTS.md +263 -0
  59. package/skills/wix-design-system/SKILL.md +129 -0
  60. package/skills/wix-design-system/references/file-structure.md +56 -0
  61. package/skills/wix-design-system/scripts/wds.cjs +531 -0
  62. package/skills/wix-headless/SKILL.md +418 -0
  63. package/skills/wix-headless/references/DISCOVERY.md +332 -0
  64. package/skills/wix-headless/references/ORCHESTRATION.md +269 -0
  65. package/skills/wix-headless/references/SETUP.md +154 -0
  66. package/skills/wix-headless/references/blog/BLOG_CONTENT.md +152 -0
  67. package/skills/wix-headless/references/blog/BLOG_PAGES.md +299 -0
  68. package/skills/wix-headless/references/blog/BLOG_SETUP.md +218 -0
  69. package/skills/wix-headless/references/blog/INSTRUCTIONS.md +32 -0
  70. package/skills/wix-headless/references/cms/CMS_FOUNDATIONS.md +373 -0
  71. package/skills/wix-headless/references/cms/FAQ_KNOWLEDGE_BASE.md +229 -0
  72. package/skills/wix-headless/references/cms/INSTRUCTIONS.md +40 -0
  73. package/skills/wix-headless/references/cms/PORTFOLIO.md +454 -0
  74. package/skills/wix-headless/references/cms/RESOURCE_LIBRARY.md +356 -0
  75. package/skills/wix-headless/references/cms/TEAM_DIRECTORY.md +299 -0
  76. package/skills/wix-headless/references/commands/install-app.md +42 -0
  77. package/skills/wix-headless/references/commands/known-apps.json +5 -0
  78. package/skills/wix-headless/references/commands/mcp-bootstrap.md +28 -0
  79. package/skills/wix-headless/references/designer/INSTRUCTIONS.md +828 -0
  80. package/skills/wix-headless/references/ecom/CART_PAGES.md +120 -0
  81. package/skills/wix-headless/references/ecom/CART_WIRING.md +103 -0
  82. package/skills/wix-headless/references/ecom/COMPONENTS_CSS.md +132 -0
  83. package/skills/wix-headless/references/ecom/INSTRUCTIONS.md +59 -0
  84. package/skills/wix-headless/references/forms/CONTACT_FORM.md +477 -0
  85. package/skills/wix-headless/references/forms/INSTRUCTIONS.md +43 -0
  86. package/skills/wix-headless/references/gift-cards/COMPONENTS.md +119 -0
  87. package/skills/wix-headless/references/gift-cards/INSTRUCTIONS.md +51 -0
  88. package/skills/wix-headless/references/gift-cards/PAGES.md +129 -0
  89. package/skills/wix-headless/references/images/INSTRUCTIONS.md +359 -0
  90. package/skills/wix-headless/references/shared/BUILD_NOISE.md +8 -0
  91. package/skills/wix-headless/references/shared/IMAGE_GENERATION.md +185 -0
  92. package/skills/wix-headless/references/shared/IMPLEMENTER.md +155 -0
  93. package/skills/wix-headless/references/shared/MCP_PREFIX.md +105 -0
  94. package/skills/wix-headless/references/shared/PRODUCTION_SHARP_EDGES.md +97 -0
  95. package/skills/wix-headless/references/shared/RETURN_CONTRACT.md +423 -0
  96. package/skills/wix-headless/references/shared/STYLING.md +117 -0
  97. package/skills/wix-headless/references/stores/BACK_IN_STOCK.md +178 -0
  98. package/skills/wix-headless/references/stores/CATEGORY_PAGES.md +86 -0
  99. package/skills/wix-headless/references/stores/COMPONENTS_CSS.md +129 -0
  100. package/skills/wix-headless/references/stores/HOME_AND_NAV.md +227 -0
  101. package/skills/wix-headless/references/stores/INSTRUCTIONS.md +96 -0
  102. package/skills/wix-headless/references/stores/PRODUCT_CATALOG_DATA.md +249 -0
  103. package/skills/wix-headless/references/stores/PRODUCT_PAGES.md +213 -0
  104. package/skills/wix-headless/references/stores/SHARED_WIRING.md +164 -0
  105. package/skills/wix-headless/references/verticals/_schema.json +160 -0
  106. package/skills/wix-headless/references/verticals/_schema.md +185 -0
  107. package/skills/wix-headless/references/verticals/blog.md +125 -0
  108. package/skills/wix-headless/references/verticals/cms.md +121 -0
  109. package/skills/wix-headless/references/verticals/ecom.md +96 -0
  110. package/skills/wix-headless/references/verticals/forms.md +106 -0
  111. package/skills/wix-headless/references/verticals/gift-cards.md +121 -0
  112. package/skills/wix-headless/references/verticals/stores.md +167 -0
  113. package/skills/wix-headless/scripts/check-manifest.mjs +198 -0
  114. package/skills/wix-headless/scripts/copy-utility-templates.mjs +153 -0
  115. package/skills/wix-headless/scripts/emit-design-tokens.mjs +77 -0
  116. package/skills/wix-headless/scripts/finalize-run-json.mjs +141 -0
  117. package/skills/wix-headless/scripts/init-site-json.mjs +63 -0
  118. package/skills/wix-headless/scripts/patch-decorative-slots.mjs +124 -0
  119. package/skills/wix-headless/scripts/plan-entity-image-waves.mjs +190 -0
  120. package/skills/wix-headless/scripts/preview.sh +45 -0
  121. package/skills/wix-headless/scripts/release.sh +73 -0
  122. package/skills/wix-headless/scripts/scaffold.sh +53 -0
  123. package/skills/wix-headless/scripts/seed-utilities.sh +55 -0
  124. package/skills/wix-headless/shared-utilities/analytics.ts +40 -0
  125. package/skills/wix-headless/shared-utilities/ricos.ts +179 -0
  126. package/skills/wix-headless/shared-utilities/wix-image.ts +72 -0
  127. package/skills/wix-headless/templates/ecom/CartBadge.tsx +84 -0
  128. package/skills/wix-headless/templates/ecom/CartView.tsx +543 -0
  129. package/skills/wix-headless/templates/ecom/cart.astro +13 -0
  130. package/skills/wix-headless/templates/ecom/components-ecom.css +215 -0
  131. package/skills/wix-headless/templates/ecom/discounts.ts +71 -0
  132. package/skills/wix-headless/templates/ecom/thank-you.astro +24 -0
  133. package/skills/wix-headless/templates/gift-cards/GiftCardPurchase.tsx +172 -0
  134. package/skills/wix-headless/templates/gift-cards/_home-teaser-snippet.astro +42 -0
  135. package/skills/wix-headless/templates/gift-cards/_nav-snippet.astro +11 -0
  136. package/skills/wix-headless/templates/gift-cards/components-gift-cards.css +219 -0
  137. package/skills/wix-headless/templates/gift-cards/gift-cards.astro +51 -0
  138. package/skills/wix-headless/templates/gift-cards/gift-cards.ts +75 -0
  139. package/skills/wix-headless/templates/stores/AddToCartButton.tsx +77 -0
  140. package/skills/wix-headless/templates/stores/BackInStockForm.tsx +176 -0
  141. package/skills/wix-headless/templates/stores/CategoryRail.astro +69 -0
  142. package/skills/wix-headless/templates/stores/ProductCard.astro +79 -0
  143. package/skills/wix-headless/templates/stores/ProductPurchase.tsx +397 -0
  144. package/skills/wix-headless/templates/stores/SeoTags.astro +21 -0
  145. package/skills/wix-headless/templates/stores/back-in-stock.ts +67 -0
  146. package/skills/wix-headless/templates/stores/categories.ts +155 -0
  147. package/skills/wix-headless/templates/stores/category/[slug].astro +130 -0
  148. package/skills/wix-headless/templates/stores/components-stores.css +295 -0
  149. package/skills/wix-headless/templates/stores/products/[slug].astro +128 -0
  150. package/skills/wix-headless/templates/stores/products/index.astro +101 -0
  151. package/skills/wix-manage/SKILL.md +280 -0
  152. package/skills/wix-manage/references/app-installation/install-wix-apps.md +155 -0
  153. package/skills/wix-manage/references/app-installation/list-installed-apps.md +124 -0
  154. package/skills/wix-manage/references/blog/how-to-create-blog-posts.md +226 -0
  155. package/skills/wix-manage/references/bookings/booking-service-policy-setup.md +95 -0
  156. package/skills/wix-manage/references/bookings/booking-system-integration-gaps.md +416 -0
  157. package/skills/wix-manage/references/bookings/bookings-staff-setup.md +255 -0
  158. package/skills/wix-manage/references/bookings/create-and-update-booking-services.md +462 -0
  159. package/skills/wix-manage/references/bookings/end-to-end-booking-flow.md +278 -0
  160. package/skills/wix-manage/references/bookings/external-calendar-integration.md +258 -0
  161. package/skills/wix-manage/references/bookings/multi-resource-service-creation.md +231 -0
  162. package/skills/wix-manage/references/calendar/configure-default-business-hours.md +226 -0
  163. package/skills/wix-manage/references/cms/cms-data-items-crud.md +422 -0
  164. package/skills/wix-manage/references/cms/cms-data-operations-extended.md +263 -0
  165. package/skills/wix-manage/references/cms/cms-ecommerce-catalog-integration.md +136 -0
  166. package/skills/wix-manage/references/cms/cms-references-and-relationships.md +160 -0
  167. package/skills/wix-manage/references/cms/cms-schema-management.md +143 -0
  168. package/skills/wix-manage/references/contacts/bulk-delete-contacts.md +73 -0
  169. package/skills/wix-manage/references/contacts/bulk-label-and-unlabel-contacts.md +67 -0
  170. package/skills/wix-manage/references/domains/domain-search-and-purchase.md +434 -0
  171. package/skills/wix-manage/references/ecommerce/api-recommendation-tracking.md +420 -0
  172. package/skills/wix-manage/references/ecommerce/flow-add-free-shipping.md +267 -0
  173. package/skills/wix-manage/references/ecommerce/flow-bundle-and-save.md +290 -0
  174. package/skills/wix-manage/references/ecommerce/flow-fix-coverage-gaps.md +300 -0
  175. package/skills/wix-manage/references/ecommerce/flow-optimize-shipping-rates.md +364 -0
  176. package/skills/wix-manage/references/ecommerce/flow-seasonal-promotion.md +315 -0
  177. package/skills/wix-manage/references/ecommerce/flow-stock-mover.md +308 -0
  178. package/skills/wix-manage/references/ecommerce/flow-upsell-boost.md +271 -0
  179. package/skills/wix-manage/references/ecommerce/goal-clear-inventory.md +118 -0
  180. package/skills/wix-manage/references/ecommerce/goal-drive-cross-sells.md +122 -0
  181. package/skills/wix-manage/references/ecommerce/goal-increase-aov.md +132 -0
  182. package/skills/wix-manage/references/ecommerce/goal-reduce-cart-abandonment.md +148 -0
  183. package/skills/wix-manage/references/ecommerce/goal-seasonal-revenue.md +146 -0
  184. package/skills/wix-manage/references/ecommerce/guardrail-discount-conflicts.md +118 -0
  185. package/skills/wix-manage/references/ecommerce/guardrail-margin-protection.md +88 -0
  186. package/skills/wix-manage/references/ecommerce/guardrail-rate-pricing-sanity.md +108 -0
  187. package/skills/wix-manage/references/ecommerce/guardrail-shipping-health.md +124 -0
  188. package/skills/wix-manage/references/ecommerce/recipe-apply-shipping-recommendations.md +299 -0
  189. package/skills/wix-manage/references/ecommerce/recommend-ecommerce-strategy.md +582 -0
  190. package/skills/wix-manage/references/ecommerce/setup-coupons.md +338 -0
  191. package/skills/wix-manage/references/ecommerce/setup-discount-rules.md +444 -0
  192. package/skills/wix-manage/references/ecommerce/setup-shipping-rates.md +86 -0
  193. package/skills/wix-manage/references/ecommerce/setup-shipping-regions.md +56 -0
  194. package/skills/wix-manage/references/ecommerce/setup-store-pickup-location.md +209 -0
  195. package/skills/wix-manage/references/ecommerce/skill-graph.md +139 -0
  196. package/skills/wix-manage/references/ecommerce/troubleshoot-checkout-delivery-dropoff.md +124 -0
  197. package/skills/wix-manage/references/ecommerce/troubleshoot-discount-not-applying.md +95 -0
  198. package/skills/wix-manage/references/events/list-events.md +203 -0
  199. package/skills/wix-manage/references/forms/create-form.md +260 -0
  200. package/skills/wix-manage/references/get-paid/create-payment-links.md +212 -0
  201. package/skills/wix-manage/references/get-paid/how-to-setup-wix-payments.md +57 -0
  202. package/skills/wix-manage/references/get-paid/payment-links-for-bookings.md +101 -0
  203. package/skills/wix-manage/references/media/upload-media-to-wix.md +216 -0
  204. package/skills/wix-manage/references/pricing-plans/create-and-update-pricing-plans.md +77 -0
  205. package/skills/wix-manage/references/pricing-plans/pricing-plans-bookings-integration.md +166 -0
  206. package/skills/wix-manage/references/restaurants/wix-restaurants-setup.md +336 -0
  207. package/skills/wix-manage/references/rich-content/ricos-converter-service.md +295 -0
  208. package/skills/wix-manage/references/site-properties/change-payment-currency-site-properties.md +59 -0
  209. package/skills/wix-manage/references/sites/create-site-from-template.md +183 -0
  210. package/skills/wix-manage/references/sites/query-sites.md +125 -0
  211. package/skills/wix-manage/references/stores/add-store-pages-to-site.md +57 -0
  212. package/skills/wix-manage/references/stores/bulk-create-products-with-options.md +1041 -0
  213. package/skills/wix-manage/references/stores/create-product-catalog-v1.md +125 -0
  214. package/skills/wix-manage/references/stores/create-product-from-image.md +824 -0
  215. package/skills/wix-manage/references/stores/create-product-with-options-catalog-v3.md +566 -0
  216. package/skills/wix-manage/references/stores/find-products-query-and-search-catalog-v3.md +194 -0
  217. package/skills/wix-manage/references/stores/query-products-catalog-v1.md +80 -0
  218. package/skills/wix-manage/references/stores/setup-online-store-catalog-v3.md +99 -0
  219. package/skills/wix-manage/references/stores/update-product-pre-order.md +213 -0
  220. package/skills/wix-manage/references/stores/update-product-with-options.md +318 -0
@@ -0,0 +1,57 @@
1
+ ---
2
+ name: "How to Setup Wix Payments"
3
+ description: Configures Wix Payments as the payment provider. Covers eligibility checking, business verification, bank account setup, and payment method configuration (cards, PayPal, Apple Pay).
4
+ ---
5
+ # How to Set Up Wix Payments
6
+
7
+ This recipe covers the setup flow needed before creating payment links or collecting payments.
8
+
9
+ ## Step 1: Collect required user inputs
10
+
11
+ Before connecting Wix Payments, collect and confirm:
12
+
13
+ 1. Terms acceptance: https://www.wix.com/about/terms-of-payments
14
+ 2. First name
15
+ 3. Last name
16
+ 4. Product/service description (minimum meaningful business description)
17
+
18
+ ## Step 2: Connect Wix Payments account
19
+
20
+ Call:
21
+
22
+ - `POST https://www.wixapis.com/payments/v1/wix-payments-account/connect`
23
+
24
+ ```json
25
+ {
26
+ "account": {
27
+ "firstName": "<USER_FIRST_NAME>",
28
+ "lastName": "<USER_LAST_NAME>",
29
+ "tosAccepted": true,
30
+ "productDescription": "<PRODUCT_DESCRIPTION>"
31
+ }
32
+ }
33
+ ```
34
+
35
+ ## Step 3: Handle common setup blockers
36
+
37
+ ### Location-related failure
38
+
39
+ If setup fails due to location details, update the business location and retry:
40
+
41
+ - `PUT https://www.wixapis.com/locations/v1/locations/{locationId}`
42
+ - Reference: [Update Location](https://dev.wix.com/docs/api-reference/business-management/locations/update-location)
43
+
44
+ ### Already connected
45
+
46
+ If the API returns an "already connected" style response, skip reconnect and continue with onboarding checks.
47
+
48
+ ## Step 4: Complete dashboard onboarding
49
+
50
+ 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.
51
+
52
+ ## Important Notes
53
+
54
+ 1. Never invent or assume user identity/business details.
55
+ 2. Always obtain explicit user consent before calling connect.
56
+ 3. Use the exact accepted values provided by the user.
57
+ 4. Verify readiness by testing a real payment flow (for example, create payment link) after setup.
@@ -0,0 +1,101 @@
1
+ ---
2
+ name: "Payment Links for Bookings"
3
+ description: Creates payment links for unpaid bookings using Payment Links API. Links booking IDs to payment requests with proper redirect handling.
4
+ ---
5
+ # Payment Links for Bookings
6
+
7
+ Use this recipe to collect payment for booking-related flows by generating payment links with the Payment Links API.
8
+
9
+ ## When to Use Which Type
10
+
11
+ ### Use `ECOM_ORDER` for existing unpaid orders
12
+
13
+ If a booking already has an associated unpaid eCommerce order, create an `ECOM_ORDER` payment link.
14
+
15
+ ```json
16
+ {
17
+ "paymentLink": {
18
+ "title": "Booking Balance",
19
+ "currency": "USD",
20
+ "type": "ECOM_ORDER",
21
+ "paymentsLimit": 1,
22
+ "ecomOrderPaymentLink": {
23
+ "orderId": "ORDER_ID",
24
+ "amount": "50"
25
+ }
26
+ }
27
+ }
28
+ ```
29
+
30
+ Notes:
31
+ - `orderId` must exist and be unpaid.
32
+ - `ECOM_ORDER` links require `paymentsLimit: 1`.
33
+
34
+ ### Use `ECOM` for ad-hoc booking charges
35
+
36
+ If there is no existing order, create an `ECOM` payment link with custom line items.
37
+
38
+ ```json
39
+ {
40
+ "paymentLink": {
41
+ "title": "Booking Fee",
42
+ "currency": "USD",
43
+ "type": "ECOM",
44
+ "ecomPaymentLink": {
45
+ "lineItems": [
46
+ {
47
+ "type": "CUSTOM",
48
+ "customItem": {
49
+ "name": "Booking Fee",
50
+ "quantity": 1,
51
+ "price": "50.00"
52
+ }
53
+ }
54
+ ]
55
+ }
56
+ }
57
+ }
58
+ ```
59
+
60
+ ## Send Flow
61
+
62
+ Creating a payment link does not deliver it. Send it explicitly:
63
+
64
+ - `POST https://www.wixapis.com/payment-links/v1/payment-links/{paymentLinkId}/send`
65
+
66
+ ```json
67
+ {
68
+ "paymentLinkId": "PAYMENT_LINK_ID",
69
+ "recipients": [
70
+ {
71
+ "contactId": "CONTACT_ID",
72
+ "sendMethods": ["EMAIL_METHOD"]
73
+ }
74
+ ]
75
+ }
76
+ ```
77
+
78
+ ## Prerequisites
79
+
80
+ Before creating booking payment links, ensure:
81
+
82
+ 1. Site is premium.
83
+ 2. Site is published.
84
+ 3. Site is set up to accept payments.
85
+ 4. Required payment-link permissions are granted to the app.
86
+ 5. Recipient contacts exist if you plan to send links.
87
+
88
+ ## Common Errors
89
+
90
+ | Error Code | Meaning |
91
+ |------------|---------|
92
+ | `UNPUBLISHED_SITE` | Site must be published before creating payment links |
93
+ | `MISSING_ACCEPT_PAYMENTS` | Site is not set up to accept payments |
94
+ | `ORDER_NOT_FOUND` | The provided order ID does not exist |
95
+ | `INVALID_PAYMENTS_LIMIT_FOR_ECOM_ORDER_PAYMENT_LINK` | `ECOM_ORDER` links require `paymentsLimit: 1` |
96
+ | `RECIPIENT_NOT_FOUND` | Recipient contact ID does not exist |
97
+
98
+ ## API Documentation References
99
+
100
+ - [Create Payment Link](https://dev.wix.com/docs/api-reference/business-management/get-paid/payment-links/payment-links/create-payment-link)
101
+ - [Send Payment Link](https://dev.wix.com/docs/api-reference/business-management/get-paid/payment-links/payment-links/send-payment-link)
@@ -0,0 +1,216 @@
1
+ ---
2
+ name: "Upload Media to Wix"
3
+ description: Uploads images and files to the Wix Media Manager using the Import File API. Covers importing from external URLs, checking file status, and using the returned wixstatic.com URL in other APIs.
4
+ ---
5
+ # RECIPE: Upload Media to Wix Media Manager
6
+
7
+ Learn how to upload images and files to a Wix site's Media Manager using the REST API.
8
+
9
+ ---
10
+
11
+ ## Overview
12
+
13
+ The Wix Media Manager stores all media files for a site. When you need to use images or files in other Wix APIs, you should first upload them to the Media Manager to get a reliable wixstatic.com URL.
14
+
15
+ **Key Points:**
16
+ - Uploaded files are permanently stored on Wix servers
17
+ - You get back a `url` (wixstatic.com) that works reliably in other APIs
18
+ - External URLs can fail if the source server blocks requests - Media Manager URLs never fail
19
+
20
+ ---
21
+
22
+ ## Method: Import File from External URL
23
+
24
+ The simplest way to add media is to import it from an external URL. Wix will download and store the file.
25
+
26
+ ### API Endpoint
27
+
28
+ ```
29
+ POST https://www.wixapis.com/site-media/v1/files/import
30
+ ```
31
+
32
+ ### Request Example
33
+
34
+ ```bash
35
+ curl -X POST 'https://www.wixapis.com/site-media/v1/files/import' \
36
+ -H 'Content-Type: application/json' \
37
+ -H 'Authorization: <AUTH>' \
38
+ -d '{
39
+ "url": "https://images.unsplash.com/photo-1563729784474-d77dbb933a9e?w=400",
40
+ "mimeType": "image/jpeg",
41
+ "displayName": "My Image"
42
+ }'
43
+ ```
44
+
45
+ ### Request Parameters
46
+
47
+ | Parameter | Required | Description |
48
+ |-----------|----------|-------------|
49
+ | `url` | Yes | The external URL of the file to import |
50
+ | `mimeType` | Recommended | MIME type (e.g., `image/jpeg`, `image/png`). If omitted, Wix tries to detect it |
51
+ | `displayName` | No | Display name in Media Manager. Include extension (e.g., `My Image.jpg`) |
52
+ | `parentFolderId` | No | Folder ID to store the file. Defaults to `media-root` |
53
+
54
+ ### Response Example
55
+
56
+ ```json
57
+ {
58
+ "file": {
59
+ "id": "e6a89e_19dae9fef9bb48a6b5e392d0d2e5b95d~mv2.jpg",
60
+ "displayName": "My Image.jpg",
61
+ "url": "https://static.wixstatic.com/media/e6a89e_19dae9fef9bb48a6b5e392d0d2e5b95d~mv2.jpg",
62
+ "parentFolderId": "media-root",
63
+ "mediaType": "IMAGE",
64
+ "operationStatus": "PENDING",
65
+ "sizeInBytes": "31911"
66
+ }
67
+ }
68
+ ```
69
+
70
+ ### Key Response Fields
71
+
72
+ | Field | Description |
73
+ |-------|-------------|
74
+ | `id` | Media ID |
75
+ | `url` | **The wixstatic.com URL - use this in other APIs** |
76
+ | `operationStatus` | `PENDING` → `READY` when processed, or `FAILED` if import failed |
77
+
78
+ > **Can I Use the URL Immediately?**
79
+ >
80
+ > **In most cases, yes.** The returned `wixstatic.com` URL typically works immediately for basic use cases like adding to products or blog posts.
81
+ >
82
+ > **Wait for READY when:**
83
+ > - You need image dimensions or metadata
84
+ > - You're using image transformations (resize, crop)
85
+ > - You want guaranteed consistency for critical operations
86
+ >
87
+ > **Practical approach:** Try using the URL immediately. If it fails, poll until `operationStatus: "READY"`.
88
+
89
+ ---
90
+
91
+ ## Checking File Status
92
+
93
+ After importing, the file goes through async processing. For guaranteed consistency, verify `operationStatus: "READY"` before using the file.
94
+
95
+ ### Get File by ID (Recommended)
96
+
97
+ Use this endpoint to check the status of a specific file:
98
+
99
+ ```bash
100
+ curl -X GET 'https://www.wixapis.com/site-media/v1/files/get-file-by-id?fileId={fileId}' \
101
+ -H 'Authorization: <AUTH>'
102
+ ```
103
+
104
+ **Example:**
105
+
106
+ ```bash
107
+ curl -X GET 'https://www.wixapis.com/site-media/v1/files/get-file-by-id?fileId=e6a89e_9d32c0dbae954582bce7b2bf35981ca6~mv2.jpg' \
108
+ -H 'Authorization: <AUTH>'
109
+ ```
110
+
111
+ ### List Recent Files (Alternative)
112
+
113
+ If you need to find files without knowing the ID:
114
+
115
+ ```bash
116
+ curl -X GET 'https://www.wixapis.com/site-media/v1/files?parentFolderId=media-root&mediaTypes=IMAGE&sort.fieldName=updatedDate&sort.order=DESC&paging.limit=5' \
117
+ -H 'Authorization: <AUTH>'
118
+ ```
119
+
120
+ ### Status Values
121
+
122
+ | Status | Meaning |
123
+ |--------|---------|
124
+ | `PENDING` | Still processing - wait before using |
125
+ | `READY` | File is ready to use |
126
+ | `FAILED` | Import failed |
127
+
128
+ ### Response When Ready
129
+
130
+ ```json
131
+ {
132
+ "files": [{
133
+ "id": "e6a89e_19dae9fef9bb48a6b5e392d0d2e5b95d~mv2.jpg",
134
+ "url": "https://static.wixstatic.com/media/e6a89e_19dae9fef9bb48a6b5e392d0d2e5b95d~mv2.jpg",
135
+ "operationStatus": "READY",
136
+ "media": {
137
+ "image": {
138
+ "image": {
139
+ "height": 600,
140
+ "width": 400
141
+ }
142
+ }
143
+ },
144
+ "labels": ["cupcakes", "pastry", "dessert"]
145
+ }]
146
+ }
147
+ ```
148
+
149
+ > **Note:** Wix automatically generates labels (tags) for images using AI.
150
+
151
+ ---
152
+
153
+ ## Alternative: Upload from Local Device
154
+
155
+ If you need to upload files from a local device (not from a URL), use the two-step upload process:
156
+
157
+ ### Step 1: Generate Upload URL
158
+
159
+ ```bash
160
+ curl -X POST 'https://www.wixapis.com/site-media/v1/files/generate-upload-url' \
161
+ -H 'Content-Type: application/json' \
162
+ -H 'Authorization: <AUTH>' \
163
+ -d '{
164
+ "mimeType": "image/jpeg",
165
+ "fileName": "my-photo.jpg"
166
+ }'
167
+ ```
168
+
169
+ ### Step 2: Upload to the Generated URL
170
+
171
+ ```bash
172
+ curl -X PUT '<UPLOAD_URL_FROM_RESPONSE>' \
173
+ -H 'Content-Type: image/jpeg' \
174
+ --data-binary @my-photo.jpg
175
+ ```
176
+
177
+ > **Note:** For files larger than 10MB, use the Resumable Upload URL API instead.
178
+
179
+ ---
180
+
181
+ ## Common Issues
182
+
183
+ ### Issue 1: Import Fails (operationStatus: FAILED)
184
+
185
+ **Problem:** The file shows `operationStatus: "FAILED"` after import.
186
+
187
+ **Causes:**
188
+ - Source server blocks external requests (e.g., Wikipedia, some CDNs)
189
+ - Source server requires authentication
190
+ - Invalid URL or file not found
191
+ - File type not supported
192
+
193
+ **Solution:** Use image sources that allow hotlinking:
194
+ - Unsplash (`images.unsplash.com`)
195
+ - Pexels (`images.pexels.com`)
196
+ - Your own hosted images
197
+ - Public cloud storage (S3, GCS with public access)
198
+
199
+ ### Issue 2: File Stuck in PENDING
200
+
201
+ **Problem:** File stays in `PENDING` status for a long time.
202
+
203
+ **Solution:**
204
+ - Large files take longer to process
205
+ - Check back after a few seconds
206
+ - If still pending after 30+ seconds, the import may have silently failed
207
+
208
+ ---
209
+
210
+ ## Summary
211
+
212
+ | Step | Action | Result |
213
+ |------|--------|--------|
214
+ | 1 | Call Import File API with external URL | Get file `id` and `url` with status `PENDING` |
215
+ | 2 | Poll List Files API | Wait for `operationStatus: "READY"` |
216
+ | 3 | Use in other APIs | Use the `url` field (wixstatic.com URL) |
@@ -0,0 +1,77 @@
1
+ ---
2
+ name: "Create and Update Pricing Plans"
3
+ description: Creates subscription and one-time payment plans using Plans API. Covers pricing models (recurring, one-time, free), trial periods, perks configuration, and plan visibility.
4
+ ---
5
+ # Technical Step-by-Step Instructions: Creating or Updating a Wix Pricing Plans (Real-World, API-First)
6
+
7
+ ## Description
8
+ Below are the recommended steps to successfully create or update a Wix Pricing Plans (or several at once) on Wix and attach a booking session to a pricing plan, with real-world troubleshooting and fixes for common API issues.
9
+
10
+ ---
11
+
12
+ ## Overview
13
+ Wix Pricing Plans includes Plans that allows Wix users to build a customized membership plan experiences and sell them to their customers. Pricing plans can also have bundled booking session as benefits.
14
+
15
+ - With Plans, a site owner can create different types of plans, such as, free, one-time or recurring subscriptions and memberships.
16
+ - With Benefits, a site owner can connect other wix apps like booking service to a pricing plan subscription or membership. Read the full list of pricing plan integration [here](https://dev.wix.com/docs/api-reference/business-solutions/pricing-plans/introduction#integrations).
17
+
18
+ ### IMPORTANT NOTES
19
+ - Always Prioritize Reading Full API Method Documentation: this overview article provides a general workflow. However, it repeatedly stresses the importance of reading the full documentation for each specific REST method you intend to use. This is critical for understanding detailed requirements.
20
+ - Pay close attention to all required fields, data types, enum values, and specific ID types (e.g., resourceId vs. id) as defined in the detailed schema of each API endpoint. The overview article serves as a guide but doesn't replace the need to consult these specifics.
21
+
22
+ ---
23
+
24
+ ## Steps
25
+ ### 0. Read pricing plans API docs
26
+ Before proceeding to further steps I must read the following [documentation](https://dev.wix.com/docs/api-reference/business-solutions/pricing-plans/introduction) on how to form request to pricing plans API.
27
+
28
+ ### 1. Create a pricing plan
29
+ Creating a pricing plan can be done by using [create plan](https://dev.wix.com/docs/api-reference/business-solutions/pricing-plans/plans-v3/create-plan) endpoint.
30
+
31
+ ### 2. Attach integrating app entity to pricing plans
32
+
33
+ To attach integrating app entity, like bookings or blog to pricing plans read the [Benefit Programs](https://dev.wix.com/docs/api-reference/business-solutions/benefit-programs/introduction) documentation and proceed to further steps.
34
+
35
+ #### 2.1. Find program definition
36
+
37
+ Use [Get Program Definition By External Id And Namespace](https://dev.wix.com/docs/api-reference/business-solutions/benefit-programs/program-definitions/get-program-definition-by-external-id-and-namespace) endpoint to find the corresponding program definition of the plan. The call must have these query params:
38
+ - `externalId` must be equal to pricing plan id.
39
+ - `namespace` must be `@wix/pricing-plans`
40
+
41
+ Example the request in curl:
42
+ ```bash
43
+ curl --request GET \
44
+ "https://www.wixapis.com/benefit-programs/v1/program-definitions/by-namespace-and-external-id?externalId=00000000-0000-0000-0000-000000000001&namespace=@wix/pricing-plans" \
45
+ -H 'Authorization: <AUTH>' \
46
+ -H "Content-Type: application/json"
47
+ ```
48
+
49
+ #### 2.2. Create a pool definition
50
+
51
+ Only one pool definition per integrating app must be created. The pool definition should be created using [create pool definition](https://dev.wix.com/docs/api-reference/business-solutions/benefit-programs/pool-definitions/create-pool-definition) endpoint.
52
+
53
+ The request for this endpoint must adhere to these rules:
54
+ - `namespace` must be `@wix/pricing-plans`
55
+ - only one benefit can be defined in the pool definition
56
+ - benefit benefitKey must be a random generated UUID
57
+ - benefit provider app id must be the integrating app def id. For the full list of wix app def ids read [this](https://dev.wix.com/docs/api-reference/articles/get-started/apps-created-by-wix) article.
58
+ - benefit price must be only 1 or 0. 0 - if you want the benefit to have unlimited credits and 1 - for the benefit to be limited.
59
+ - `creditConfiguration` must be empty if the benefit is unlimited
60
+
61
+ #### 2.3. Create benefit items
62
+
63
+ This step is needed to attach the integrating app entity to benefit program. This is done by using [bulk create items](https://dev.wix.com/docs/api-reference/business-solutions/benefit-programs/items/bulk-create-items) endpoint.
64
+
65
+ Each item in the request for this endpoint must adhere to these rules:
66
+ - `namespace` must be `@wix/pricing-plans`
67
+ - `category` must be empty string
68
+ - provider app id must be the integrating app def id. For the full list of wix app def ids read [this](https://dev.wix.com/docs/api-reference/articles/get-started/apps-created-by-wix) article.
69
+ - `itemSetId` must set to the created pool definition benefit item set id.
70
+ - `externalId` must be set to the integrating app entity id, example: booking service id or blog post id.
71
+
72
+ ## Pricing plans REST API Documentation Reference
73
+ - [Create plan](https://dev.wix.com/docs/api-reference/business-solutions/pricing-plans/plans-v3/create-plan)
74
+ - [Get plan](https://dev.wix.com/docs/api-reference/business-solutions/pricing-plans/plans-v3/get-plan)
75
+ - [Update plan](https://dev.wix.com/docs/api-reference/business-solutions/pricing-plans/plans-v3/update-plan)
76
+ - [Query Plans](https://dev.wix.com/docs/api-reference/business-solutions/pricing-plans/plans-v3/query-plans)
77
+ - [Pricing Plans Introduction](https://dev.wix.com/docs/api-reference/business-solutions/pricing-plans/introduction)
@@ -0,0 +1,166 @@
1
+ ---
2
+ name: "Pricing Plans Bookings Integration"
3
+ description: Links Pricing Plans to Bookings services using the Benefit Programs API. Enables package deals and memberships that grant booking access.
4
+ ---
5
+
6
+ # Technical Step-by-Step Instructions: Integrating Wix Pricing Plans with Bookings Services (Real-World, API-First)
7
+
8
+ ## Description
9
+
10
+ Below are the recommended steps to successfully integrate Wix Pricing Plans with Wix Bookings services, enabling customers to purchase packages and memberships for booking sessions. This recipe covers the complete workflow including the required Benefit Programs integration.
11
+
12
+ ---
13
+
14
+ ## Prerequisites
15
+
16
+ ### Required App Installations
17
+
18
+ Before starting the integration, ensure the following apps are installed on the site:
19
+
20
+ 1. **Wix Bookings** - Usually pre-installed, but verify using site queries
21
+ 2. **Pricing Plans** - Must be installed if not present
22
+ - Install if you encounter 428 "App not installed" errors
23
+
24
+ ### App Installation Process
25
+
26
+ If you receive app-related errors, install the missing app using the Apps Installer API.
27
+
28
+ **Steps:**
29
+
30
+ 1. Identify the required app through error messages or API documentation
31
+ 2. Use the Apps Installer API to install the missing app
32
+ 3. Verify installation before proceeding
33
+
34
+ **For detailed app installation procedures, refer to:**
35
+
36
+ - [Apps Installer API Documentation](https://dev.wix.com/docs/api-reference/business-management/app-installation/install-app)
37
+ - Business setup recipes for app installation workflows
38
+ - API error messages which typically indicate the required app and installation steps
39
+
40
+ ## Overview
41
+
42
+ Integrating Pricing Plans with Bookings allows businesses to offer:
43
+
44
+ - **Packages**: Fixed session count (e.g., "10 sessions") that can be used within validity period
45
+ - **Memberships with session limits**: Sessions per billing cycle (e.g., "10 sessions a month")
46
+ - **Unlimited memberships**: Unlimited access during subscription period (shows as "Unlimited Sessions")
47
+
48
+ The integration requires coordination between three APIs:
49
+
50
+ 1. **Pricing Plans API** - Creates the plan structure and pricing
51
+ 2. **Benefit Programs API** - Creates the bridge between plans and services
52
+ 3. **Bookings API** - Services automatically support pricing plan payments
53
+
54
+ ### IMPORTANT NOTES
55
+
56
+ - The integration requires using all three APIs in sequence - there's no direct connection between Pricing Plans and Bookings
57
+ - This is a complex integration that requires careful error handling and state management
58
+ - Service `payment.options.pricingPlan` automatically becomes `true` when benefit programs are properly connected
59
+ - The benefit program `externalId` must exactly match the pricing plan `id` for the connection to work
60
+ - **Minimum Duration Requirements**: Plans must have minimum 7-day validity periods - cannot create 1-day plans
61
+ - **Revision Number Management**: The Benefit Programs API uses revision numbers that can conflict with concurrent operations
62
+
63
+ ---
64
+
65
+ ## Steps
66
+
67
+ ### 1. Create the Pricing Plan
68
+
69
+ Create the pricing plan first using the Pricing Plans API. You can create either:
70
+
71
+ - **Package plans** using `singlePaymentForDuration` pricing model with `"type": "bookings-package"` in `clientData`
72
+ - **Membership plans** using `subscription` pricing model with `"type": "bookings-membership"` in `clientData`
73
+
74
+ **Important Validation Requirements:**
75
+
76
+ - `validity.duration` must be minimum 7 days (`P7D` format)
77
+ - Cannot use `P1D` or shorter periods due to API validation
78
+ - For subscription plans, billing cycles have similar minimum requirements
79
+
80
+ Keep the returned `plan.id` for the next step.
81
+
82
+ ### 2. Create Benefit Program Definition
83
+
84
+ Use the Benefit Programs API to create the program definition that links to your pricing plan. The `externalId` must exactly match the pricing plan `id` from step 1, and use `"@wix/pricing-plans"` as the namespace.
85
+
86
+ **Error Handling Note**: If you receive "Entity already exists" errors, the program definition may already exist from a previous attempt. Query existing programs first or handle the error gracefully.
87
+
88
+ ### 3. Create Benefit Definition for Bookings Service
89
+
90
+ Create the benefit definition that connects the program to your specific booking service:
91
+
92
+ - For **packages with session limits**: Include `creditAmount` set to the desired session count
93
+ - For **unlimited memberships**: Omit the `creditAmount` field entirely
94
+ - Always use the correct `serviceId` from your bookings service and `"@wix/pricing-plans"` namespace
95
+
96
+ **Revision Number Handling**: The Benefit Programs API requires revision numbers. If operations fail due to revision conflicts, retrieve the current revision number and retry.
97
+
98
+ ### 4. Verify Service Integration
99
+
100
+ Query the service to confirm integration is working. The service should now show `payment.options.pricingPlan: true` and the plan should appear in the booking UI as a payment option.
101
+
102
+ ### IMPORTANT NOTES
103
+
104
+ - **Sequence matters**: Create pricing plan → benefit program definition → benefit definition. Wrong order will cause "Plan not found" errors
105
+ - **Complex State Management**: This integration involves multiple APIs with different revision systems and error handling patterns
106
+ - **ID relationships**:
107
+ - Pricing Plan `id` → Benefit Program Definition `externalId`
108
+ - Service `id` → Benefit Definition `serviceId`
109
+ - Program Definition `id` → Benefit Definition `programDefinitionId`
110
+ - **Session behavior**:
111
+ - With `creditAmount`: Users consume credits per session
112
+ - Without `creditAmount`: Users get unlimited access during subscription
113
+ - **Namespace requirement**: Always use `"@wix/pricing-plans"` as namespace for pricing plan integrations
114
+ - **Service updates**: Services automatically update when benefit programs are connected - no manual service modification needed
115
+
116
+ ### Troubleshooting Common Issues
117
+
118
+ **"App not installed" Error (428):**
119
+
120
+ - Install Pricing Plans app using Apps Installer API
121
+ - Verify installation before proceeding with plan creation
122
+
123
+ **"Plan not found" Error:**
124
+
125
+ - Verify `externalId` exactly matches pricing plan `id`
126
+ - Ensure pricing plan was created successfully before creating benefit program
127
+ - Check that the plan hasn't been deleted or modified
128
+
129
+ **"Entity already exists" Error:**
130
+
131
+ - Query existing benefit program definitions to check for duplicates
132
+ - Consider updating existing programs instead of creating new ones
133
+ - Implement proper error handling for idempotent operations
134
+
135
+ **Service doesn't show pricing plan option:**
136
+
137
+ - Check that benefit definition has correct `serviceId`
138
+ - Verify all three entities (plan, program definition, benefit definition) were created successfully
139
+ - Confirm service query shows `payment.options.pricingPlan: true`
140
+
141
+ **Credits not working correctly:**
142
+
143
+ - For packages: Ensure `creditAmount` is set to desired session count
144
+ - For unlimited: Ensure `creditAmount` is omitted entirely
145
+ - Verify the benefit definition is properly linked to the correct program definition
146
+
147
+ **Minimum Duration Validation Errors:**
148
+
149
+ - Ensure `validity.duration` is at least `P7D` (7 days)
150
+ - Adjust single-session plans to weekly validity instead of daily
151
+ - For subscription plans, use appropriate billing cycle minimums
152
+
153
+ **Revision Number Conflicts:**
154
+
155
+ - Implement retry logic with fresh revision number retrieval
156
+ - Handle concurrent operations gracefully
157
+ - Consider queuing operations if dealing with high-frequency updates
158
+
159
+ ## API Documentation References
160
+
161
+ - [Create Plan](https://dev.wix.com/docs/api-reference/business-solutions/pricing-plans/plans-v3/create-plan) — `POST https://www.wixapis.com/pricing-plans/v3/plans`
162
+ - [Create Program Definition](https://dev.wix.com/docs/api-reference/business-solutions/benefit-programs/program-definitions/create-program-definition) — `POST https://www.wixapis.com/_api/benefit-programs/v1/program-definitions`
163
+ - [Pricing Plans API](https://dev.wix.com/docs/api-reference/business-solutions/pricing-plans/introduction)
164
+ - [Benefit Programs API](https://dev.wix.com/docs/api-reference/business-solutions/benefit-programs/introduction)
165
+ - [Bookings Services API](https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/introduction)
166
+ - [Apps Installer API](https://dev.wix.com/docs/api-reference/business-management/app-installation/install-app)