@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.
- package/LICENSE +21 -0
- package/README.md +111 -0
- package/package.json +29 -0
- package/skills/wix-app/SKILL.md +344 -0
- package/skills/wix-app/references/APP_IDENTIFIERS.md +35 -0
- package/skills/wix-app/references/APP_MARKET_REVIEW.md +311 -0
- package/skills/wix-app/references/APP_VALIDATION.md +171 -0
- package/skills/wix-app/references/BACKEND_API.md +233 -0
- package/skills/wix-app/references/BACKEND_EVENT.md +116 -0
- package/skills/wix-app/references/CODE_QUALITY.md +33 -0
- package/skills/wix-app/references/CUSTOM_ELEMENT_WIDGET.md +587 -0
- package/skills/wix-app/references/DASHBOARD_MENU_PLUGIN.md +157 -0
- package/skills/wix-app/references/DASHBOARD_MODAL.md +283 -0
- package/skills/wix-app/references/DASHBOARD_PAGE.md +403 -0
- package/skills/wix-app/references/DASHBOARD_PLUGIN.md +205 -0
- package/skills/wix-app/references/DATA_COLLECTION.md +451 -0
- package/skills/wix-app/references/DOCUMENTATION.md +42 -0
- package/skills/wix-app/references/EDITOR_REACT_COMPONENT.md +65 -0
- package/skills/wix-app/references/EMBEDDED_SCRIPT.md +468 -0
- package/skills/wix-app/references/EXTENSION_REGISTRATION.md +96 -0
- package/skills/wix-app/references/SERVICE_PLUGIN.md +235 -0
- package/skills/wix-app/references/SITE_PLUGIN.md +436 -0
- package/skills/wix-app/references/STORES_VERSIONING.md +334 -0
- package/skills/wix-app/references/backend-event/COMMON-EVENTS.md +84 -0
- package/skills/wix-app/references/custom-element-widget/SETTINGS_PANEL.md +345 -0
- package/skills/wix-app/references/dashboard-menu-plugin/blog-slots.md +71 -0
- package/skills/wix-app/references/dashboard-menu-plugin/bookings-slots.md +58 -0
- package/skills/wix-app/references/dashboard-menu-plugin/crm-slots.md +8 -0
- package/skills/wix-app/references/dashboard-menu-plugin/ecommerce-slots.md +17 -0
- package/skills/wix-app/references/dashboard-menu-plugin/events-slots.md +29 -0
- package/skills/wix-app/references/dashboard-menu-plugin/restaurants-slots.md +27 -0
- package/skills/wix-app/references/dashboard-menu-plugin/stores-slots.md +35 -0
- package/skills/wix-app/references/dashboard-page/API_SPEC.md +138 -0
- package/skills/wix-app/references/dashboard-page/DASHBOARD_API.md +573 -0
- package/skills/wix-app/references/dashboard-page/DYNAMIC_PARAMETERS.md +269 -0
- package/skills/wix-app/references/dashboard-page/ECOM_NAVIGATION.md +164 -0
- package/skills/wix-app/references/dashboard-plugin/SLOTS.md +294 -0
- package/skills/wix-app/references/data-collection/WIX_DATA.md +270 -0
- package/skills/wix-app/references/data-collection/extension-template.ts +107 -0
- package/skills/wix-app/references/editor-react-component/ACCESSIBILITY.md +138 -0
- package/skills/wix-app/references/editor-react-component/COMPONENT-API.md +454 -0
- package/skills/wix-app/references/editor-react-component/COMPONENT-CONFIGURATION.md +165 -0
- package/skills/wix-app/references/editor-react-component/CSS-GUIDELINES.md +576 -0
- package/skills/wix-app/references/editor-react-component/DIRECTIONALITY.md +170 -0
- package/skills/wix-app/references/editor-react-component/EDIT-FLOW.md +6 -0
- package/skills/wix-app/references/editor-react-component/PARTS.md +25 -0
- package/skills/wix-app/references/editor-react-component/PROPS-VS-CSS.md +203 -0
- package/skills/wix-app/references/editor-react-component/REACT-GUIDELINES.md +167 -0
- package/skills/wix-app/references/editor-react-component/REACT-PATTERNS.md +137 -0
- package/skills/wix-app/references/service-plugin/ADDITIONAL-FEES.md +112 -0
- package/skills/wix-app/references/service-plugin/BOOKINGS-STAFF-SORTING.md +118 -0
- package/skills/wix-app/references/service-plugin/DISCOUNT-TRIGGERS.md +87 -0
- package/skills/wix-app/references/service-plugin/GIFT-CARDS.md +86 -0
- package/skills/wix-app/references/service-plugin/PAYMENT-SETTINGS.md +135 -0
- package/skills/wix-app/references/service-plugin/SHIPPING-RATES.md +79 -0
- package/skills/wix-app/references/service-plugin/VALIDATIONS.md +68 -0
- package/skills/wix-app/references/site-plugin/EXAMPLES.md +311 -0
- package/skills/wix-app/references/site-plugin/SLOTS.md +263 -0
- package/skills/wix-design-system/SKILL.md +129 -0
- package/skills/wix-design-system/references/file-structure.md +56 -0
- package/skills/wix-design-system/scripts/wds.cjs +531 -0
- package/skills/wix-headless/SKILL.md +418 -0
- package/skills/wix-headless/references/DISCOVERY.md +332 -0
- package/skills/wix-headless/references/ORCHESTRATION.md +269 -0
- package/skills/wix-headless/references/SETUP.md +154 -0
- package/skills/wix-headless/references/blog/BLOG_CONTENT.md +152 -0
- package/skills/wix-headless/references/blog/BLOG_PAGES.md +299 -0
- package/skills/wix-headless/references/blog/BLOG_SETUP.md +218 -0
- package/skills/wix-headless/references/blog/INSTRUCTIONS.md +32 -0
- package/skills/wix-headless/references/cms/CMS_FOUNDATIONS.md +373 -0
- package/skills/wix-headless/references/cms/FAQ_KNOWLEDGE_BASE.md +229 -0
- package/skills/wix-headless/references/cms/INSTRUCTIONS.md +40 -0
- package/skills/wix-headless/references/cms/PORTFOLIO.md +454 -0
- package/skills/wix-headless/references/cms/RESOURCE_LIBRARY.md +356 -0
- package/skills/wix-headless/references/cms/TEAM_DIRECTORY.md +299 -0
- package/skills/wix-headless/references/commands/install-app.md +42 -0
- package/skills/wix-headless/references/commands/known-apps.json +5 -0
- package/skills/wix-headless/references/commands/mcp-bootstrap.md +28 -0
- package/skills/wix-headless/references/designer/INSTRUCTIONS.md +828 -0
- package/skills/wix-headless/references/ecom/CART_PAGES.md +120 -0
- package/skills/wix-headless/references/ecom/CART_WIRING.md +103 -0
- package/skills/wix-headless/references/ecom/COMPONENTS_CSS.md +132 -0
- package/skills/wix-headless/references/ecom/INSTRUCTIONS.md +59 -0
- package/skills/wix-headless/references/forms/CONTACT_FORM.md +477 -0
- package/skills/wix-headless/references/forms/INSTRUCTIONS.md +43 -0
- package/skills/wix-headless/references/gift-cards/COMPONENTS.md +119 -0
- package/skills/wix-headless/references/gift-cards/INSTRUCTIONS.md +51 -0
- package/skills/wix-headless/references/gift-cards/PAGES.md +129 -0
- package/skills/wix-headless/references/images/INSTRUCTIONS.md +359 -0
- package/skills/wix-headless/references/shared/BUILD_NOISE.md +8 -0
- package/skills/wix-headless/references/shared/IMAGE_GENERATION.md +185 -0
- package/skills/wix-headless/references/shared/IMPLEMENTER.md +155 -0
- package/skills/wix-headless/references/shared/MCP_PREFIX.md +105 -0
- package/skills/wix-headless/references/shared/PRODUCTION_SHARP_EDGES.md +97 -0
- package/skills/wix-headless/references/shared/RETURN_CONTRACT.md +423 -0
- package/skills/wix-headless/references/shared/STYLING.md +117 -0
- package/skills/wix-headless/references/stores/BACK_IN_STOCK.md +178 -0
- package/skills/wix-headless/references/stores/CATEGORY_PAGES.md +86 -0
- package/skills/wix-headless/references/stores/COMPONENTS_CSS.md +129 -0
- package/skills/wix-headless/references/stores/HOME_AND_NAV.md +227 -0
- package/skills/wix-headless/references/stores/INSTRUCTIONS.md +96 -0
- package/skills/wix-headless/references/stores/PRODUCT_CATALOG_DATA.md +249 -0
- package/skills/wix-headless/references/stores/PRODUCT_PAGES.md +213 -0
- package/skills/wix-headless/references/stores/SHARED_WIRING.md +164 -0
- package/skills/wix-headless/references/verticals/_schema.json +160 -0
- package/skills/wix-headless/references/verticals/_schema.md +185 -0
- package/skills/wix-headless/references/verticals/blog.md +125 -0
- package/skills/wix-headless/references/verticals/cms.md +121 -0
- package/skills/wix-headless/references/verticals/ecom.md +96 -0
- package/skills/wix-headless/references/verticals/forms.md +106 -0
- package/skills/wix-headless/references/verticals/gift-cards.md +121 -0
- package/skills/wix-headless/references/verticals/stores.md +167 -0
- package/skills/wix-headless/scripts/check-manifest.mjs +198 -0
- package/skills/wix-headless/scripts/copy-utility-templates.mjs +153 -0
- package/skills/wix-headless/scripts/emit-design-tokens.mjs +77 -0
- package/skills/wix-headless/scripts/finalize-run-json.mjs +141 -0
- package/skills/wix-headless/scripts/init-site-json.mjs +63 -0
- package/skills/wix-headless/scripts/patch-decorative-slots.mjs +124 -0
- package/skills/wix-headless/scripts/plan-entity-image-waves.mjs +190 -0
- package/skills/wix-headless/scripts/preview.sh +45 -0
- package/skills/wix-headless/scripts/release.sh +73 -0
- package/skills/wix-headless/scripts/scaffold.sh +53 -0
- package/skills/wix-headless/scripts/seed-utilities.sh +55 -0
- package/skills/wix-headless/shared-utilities/analytics.ts +40 -0
- package/skills/wix-headless/shared-utilities/ricos.ts +179 -0
- package/skills/wix-headless/shared-utilities/wix-image.ts +72 -0
- package/skills/wix-headless/templates/ecom/CartBadge.tsx +84 -0
- package/skills/wix-headless/templates/ecom/CartView.tsx +543 -0
- package/skills/wix-headless/templates/ecom/cart.astro +13 -0
- package/skills/wix-headless/templates/ecom/components-ecom.css +215 -0
- package/skills/wix-headless/templates/ecom/discounts.ts +71 -0
- package/skills/wix-headless/templates/ecom/thank-you.astro +24 -0
- package/skills/wix-headless/templates/gift-cards/GiftCardPurchase.tsx +172 -0
- package/skills/wix-headless/templates/gift-cards/_home-teaser-snippet.astro +42 -0
- package/skills/wix-headless/templates/gift-cards/_nav-snippet.astro +11 -0
- package/skills/wix-headless/templates/gift-cards/components-gift-cards.css +219 -0
- package/skills/wix-headless/templates/gift-cards/gift-cards.astro +51 -0
- package/skills/wix-headless/templates/gift-cards/gift-cards.ts +75 -0
- package/skills/wix-headless/templates/stores/AddToCartButton.tsx +77 -0
- package/skills/wix-headless/templates/stores/BackInStockForm.tsx +176 -0
- package/skills/wix-headless/templates/stores/CategoryRail.astro +69 -0
- package/skills/wix-headless/templates/stores/ProductCard.astro +79 -0
- package/skills/wix-headless/templates/stores/ProductPurchase.tsx +397 -0
- package/skills/wix-headless/templates/stores/SeoTags.astro +21 -0
- package/skills/wix-headless/templates/stores/back-in-stock.ts +67 -0
- package/skills/wix-headless/templates/stores/categories.ts +155 -0
- package/skills/wix-headless/templates/stores/category/[slug].astro +130 -0
- package/skills/wix-headless/templates/stores/components-stores.css +295 -0
- package/skills/wix-headless/templates/stores/products/[slug].astro +128 -0
- package/skills/wix-headless/templates/stores/products/index.astro +101 -0
- package/skills/wix-manage/SKILL.md +280 -0
- package/skills/wix-manage/references/app-installation/install-wix-apps.md +155 -0
- package/skills/wix-manage/references/app-installation/list-installed-apps.md +124 -0
- package/skills/wix-manage/references/blog/how-to-create-blog-posts.md +226 -0
- package/skills/wix-manage/references/bookings/booking-service-policy-setup.md +95 -0
- package/skills/wix-manage/references/bookings/booking-system-integration-gaps.md +416 -0
- package/skills/wix-manage/references/bookings/bookings-staff-setup.md +255 -0
- package/skills/wix-manage/references/bookings/create-and-update-booking-services.md +462 -0
- package/skills/wix-manage/references/bookings/end-to-end-booking-flow.md +278 -0
- package/skills/wix-manage/references/bookings/external-calendar-integration.md +258 -0
- package/skills/wix-manage/references/bookings/multi-resource-service-creation.md +231 -0
- package/skills/wix-manage/references/calendar/configure-default-business-hours.md +226 -0
- package/skills/wix-manage/references/cms/cms-data-items-crud.md +422 -0
- package/skills/wix-manage/references/cms/cms-data-operations-extended.md +263 -0
- package/skills/wix-manage/references/cms/cms-ecommerce-catalog-integration.md +136 -0
- package/skills/wix-manage/references/cms/cms-references-and-relationships.md +160 -0
- package/skills/wix-manage/references/cms/cms-schema-management.md +143 -0
- package/skills/wix-manage/references/contacts/bulk-delete-contacts.md +73 -0
- package/skills/wix-manage/references/contacts/bulk-label-and-unlabel-contacts.md +67 -0
- package/skills/wix-manage/references/domains/domain-search-and-purchase.md +434 -0
- package/skills/wix-manage/references/ecommerce/api-recommendation-tracking.md +420 -0
- package/skills/wix-manage/references/ecommerce/flow-add-free-shipping.md +267 -0
- package/skills/wix-manage/references/ecommerce/flow-bundle-and-save.md +290 -0
- package/skills/wix-manage/references/ecommerce/flow-fix-coverage-gaps.md +300 -0
- package/skills/wix-manage/references/ecommerce/flow-optimize-shipping-rates.md +364 -0
- package/skills/wix-manage/references/ecommerce/flow-seasonal-promotion.md +315 -0
- package/skills/wix-manage/references/ecommerce/flow-stock-mover.md +308 -0
- package/skills/wix-manage/references/ecommerce/flow-upsell-boost.md +271 -0
- package/skills/wix-manage/references/ecommerce/goal-clear-inventory.md +118 -0
- package/skills/wix-manage/references/ecommerce/goal-drive-cross-sells.md +122 -0
- package/skills/wix-manage/references/ecommerce/goal-increase-aov.md +132 -0
- package/skills/wix-manage/references/ecommerce/goal-reduce-cart-abandonment.md +148 -0
- package/skills/wix-manage/references/ecommerce/goal-seasonal-revenue.md +146 -0
- package/skills/wix-manage/references/ecommerce/guardrail-discount-conflicts.md +118 -0
- package/skills/wix-manage/references/ecommerce/guardrail-margin-protection.md +88 -0
- package/skills/wix-manage/references/ecommerce/guardrail-rate-pricing-sanity.md +108 -0
- package/skills/wix-manage/references/ecommerce/guardrail-shipping-health.md +124 -0
- package/skills/wix-manage/references/ecommerce/recipe-apply-shipping-recommendations.md +299 -0
- package/skills/wix-manage/references/ecommerce/recommend-ecommerce-strategy.md +582 -0
- package/skills/wix-manage/references/ecommerce/setup-coupons.md +338 -0
- package/skills/wix-manage/references/ecommerce/setup-discount-rules.md +444 -0
- package/skills/wix-manage/references/ecommerce/setup-shipping-rates.md +86 -0
- package/skills/wix-manage/references/ecommerce/setup-shipping-regions.md +56 -0
- package/skills/wix-manage/references/ecommerce/setup-store-pickup-location.md +209 -0
- package/skills/wix-manage/references/ecommerce/skill-graph.md +139 -0
- package/skills/wix-manage/references/ecommerce/troubleshoot-checkout-delivery-dropoff.md +124 -0
- package/skills/wix-manage/references/ecommerce/troubleshoot-discount-not-applying.md +95 -0
- package/skills/wix-manage/references/events/list-events.md +203 -0
- package/skills/wix-manage/references/forms/create-form.md +260 -0
- package/skills/wix-manage/references/get-paid/create-payment-links.md +212 -0
- package/skills/wix-manage/references/get-paid/how-to-setup-wix-payments.md +57 -0
- package/skills/wix-manage/references/get-paid/payment-links-for-bookings.md +101 -0
- package/skills/wix-manage/references/media/upload-media-to-wix.md +216 -0
- package/skills/wix-manage/references/pricing-plans/create-and-update-pricing-plans.md +77 -0
- package/skills/wix-manage/references/pricing-plans/pricing-plans-bookings-integration.md +166 -0
- package/skills/wix-manage/references/restaurants/wix-restaurants-setup.md +336 -0
- package/skills/wix-manage/references/rich-content/ricos-converter-service.md +295 -0
- package/skills/wix-manage/references/site-properties/change-payment-currency-site-properties.md +59 -0
- package/skills/wix-manage/references/sites/create-site-from-template.md +183 -0
- package/skills/wix-manage/references/sites/query-sites.md +125 -0
- package/skills/wix-manage/references/stores/add-store-pages-to-site.md +57 -0
- package/skills/wix-manage/references/stores/bulk-create-products-with-options.md +1041 -0
- package/skills/wix-manage/references/stores/create-product-catalog-v1.md +125 -0
- package/skills/wix-manage/references/stores/create-product-from-image.md +824 -0
- package/skills/wix-manage/references/stores/create-product-with-options-catalog-v3.md +566 -0
- package/skills/wix-manage/references/stores/find-products-query-and-search-catalog-v3.md +194 -0
- package/skills/wix-manage/references/stores/query-products-catalog-v1.md +80 -0
- package/skills/wix-manage/references/stores/setup-online-store-catalog-v3.md +99 -0
- package/skills/wix-manage/references/stores/update-product-pre-order.md +213 -0
- 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)
|