skilld
All skills
wix avatar

/wix-manage

@4895cc9 official
by Wix.comwix/skills33 stars
33

REST recipes to configure and manage a Wix site's business solutions — stores, bookings, payments, CMS, and more. Open the matching recipe for the exact endpoint, method, and payload before calling — never guess a Wix API, never write Wix dashboard URL from memory. Routes to: stores, bookings, get-paid, CMS, contacts, forms, media, app-installation, pricing-plans, restaurants, ricos rich-content, sites, blog, calendar, domains, events, site-properties, ecommerce, marketing, google-ads, google-business-profile, analytics, accessibility, seo, dashboard-navigation.

Ask your Agent

Use this Skill: https://skilld.dev/gh/wix/skills/wix-manage

This session only. Nothing lands on disk.

referencespricing-planspricing-plans-bookings-integration.md

≈2.1k tokens on demand. Your agent reads this file only when SKILL.md points to it.

Technical Step-by-Step Instructions: Integrating Wix Pricing Plans with Bookings Services (Real-World, API-First)

Description

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.

Prerequisites

Required App Installations

Before starting the integration, ensure the following apps are installed on the site:

  1. Wix Bookings - Usually pre-installed, but verify using site queries
  2. Pricing Plans - Must be installed if not present
    • Install if you encounter 428 "App not installed" errors

App Installation Process

If you receive app-related errors, install the missing app using the Apps Installer API.

Steps:

  1. Identify the required app through error messages or API documentation
  2. Use the Apps Installer API to install the missing app
  3. Verify installation before proceeding

For detailed app installation procedures, refer to:

  • Apps Installer API Documentation
  • Business setup recipes for app installation workflows
  • API error messages which typically indicate the required app and installation steps

Overview

Integrating Pricing Plans with Bookings allows businesses to offer:

  • Packages: Fixed session count (e.g., "10 sessions") that can be used within validity period
  • Memberships with session limits: Sessions per billing cycle (e.g., "10 sessions a month")
  • Unlimited memberships: Unlimited access during subscription period (shows as "Unlimited Sessions")

The integration requires coordination between three APIs:

  1. Pricing Plans API - Creates the plan structure and pricing
  2. Benefit Programs API - Creates the bridge between plans and services
  3. Bookings API - Services automatically support pricing plan payments

IMPORTANT NOTES

  • The integration requires using all three APIs in sequence - there's no direct connection between Pricing Plans and Bookings
  • This is a complex integration that requires careful error handling and state management
  • Service payment.options.pricingPlan automatically becomes true when benefit programs are properly connected
  • The benefit program externalId must exactly match the pricing plan id for the connection to work
  • Minimum Duration Requirements: Plans must have minimum 7-day validity periods - cannot create 1-day plans
  • Revision Number Management: The Benefit Programs API uses revision numbers that can conflict with concurrent operations

Steps

1. Create the Pricing Plan

Create the pricing plan first using the Pricing Plans API. You can create either:

  • Package plans using singlePaymentForDuration pricing model with "type": "bookings-package" in clientData
  • Membership plans using subscription pricing model with "type": "bookings-membership" in clientData

Important Validation Requirements:

  • validity.duration must be minimum 7 days (P7D format)
  • Cannot use P1D or shorter periods due to API validation
  • For subscription plans, billing cycles have similar minimum requirements

Keep the returned plan.id for the next step.

2. Create Benefit Program Definition

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.

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.

3. Create Benefit Definition for Bookings Service

Create the benefit definition that connects the program to your specific booking service:

  • For packages with session limits: Include creditAmount set to the desired session count
  • For unlimited memberships: Omit the creditAmount field entirely
  • Always use the correct serviceId from your bookings service and "@wix/pricing-plans" namespace

Revision Number Handling: The Benefit Programs API requires revision numbers. If operations fail due to revision conflicts, retrieve the current revision number and retry.

4. Verify Service Integration

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.

IMPORTANT NOTES

  • Sequence matters: Create pricing plan → benefit program definition → benefit definition. Wrong order will cause "Plan not found" errors
  • Complex State Management: This integration involves multiple APIs with different revision systems and error handling patterns
  • ID relationships:
    • Pricing Plan id → Benefit Program Definition externalId
    • Service id → Benefit Definition serviceId
    • Program Definition id → Benefit Definition programDefinitionId
  • Session behavior:
    • With creditAmount: Users consume credits per session
    • Without creditAmount: Users get unlimited access during subscription
  • Namespace requirement: Always use "@wix/pricing-plans" as namespace for pricing plan integrations
  • Service updates: Services automatically update when benefit programs are connected - no manual service modification needed

Troubleshooting Common Issues

"App not installed" Error (428):

  • Install Pricing Plans app using Apps Installer API
  • Verify installation before proceeding with plan creation

"Plan not found" Error:

  • Verify externalId exactly matches pricing plan id
  • Ensure pricing plan was created successfully before creating benefit program
  • Check that the plan hasn't been deleted or modified

"Entity already exists" Error:

  • Query existing benefit program definitions to check for duplicates
  • Consider updating existing programs instead of creating new ones
  • Implement proper error handling for idempotent operations

Service doesn't show pricing plan option:

  • Check that benefit definition has correct serviceId
  • Verify all three entities (plan, program definition, benefit definition) were created successfully
  • Confirm service query shows payment.options.pricingPlan: true

Credits not working correctly:

  • For packages: Ensure creditAmount is set to desired session count
  • For unlimited: Ensure creditAmount is omitted entirely
  • Verify the benefit definition is properly linked to the correct program definition

Minimum Duration Validation Errors:

  • Ensure validity.duration is at least P7D (7 days)
  • Adjust single-session plans to weekly validity instead of daily
  • For subscription plans, use appropriate billing cycle minimums

Revision Number Conflicts:

  • Implement retry logic with fresh revision number retrieval
  • Handle concurrent operations gracefully
  • Consider queuing operations if dealing with high-frequency updates

API Documentation References

Source: SKILL.md on GitHub

Third-party checks

1 warning1d4 checks · Risk SAFE
  • Gen Agent Trust Hub1d

    The wix-manage skill is an extensive collection of management recipes for Wix sites, covering business solutions such as eCommerce, Bookings, SEO, and site provisioning. It utilizes official Wix REST endpoints and incorporates robust safety patterns, including mandatory user confirmation for sensitive operations and careful validation of site data before mutation.

  • Socket1d

    No alerts

  • Snyk1d

    Risk: MEDIUM · 1 issue

  • ZeroLeaks5mo

    Score: 93/100 · 2 sections analyzed

Provenance

Signed by skilld at 4895cc9. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated yesterday

Capability

compatibility
Requires Wix REST API access (API key or OAuth).

Topics

  • wix
  • rest-api
  • ecommerce
  • bookings
  • cms
  • contacts
  • blog
  • domains
  • restaurants
  • site-configuration
  • api-integration

README badge

README badge for wix/skills/wix-manage

What it does

REST API operations for configuring Wix business solutions including stores, bookings, CMS, contacts, domains, and ecommerce. Routes to site setup, entity management (products, services, staff), bulk administrative operations, and server-to-server integrations across Wix's business app ecosystem.

Generated from the current SKILL.md.

Frequently asked

Do I need API credentials to use these recipes?
Yes. The skill requires Wix REST API access via either an API key or OAuth token to execute any management operations.
Can I use these recipes to display data on my site frontend?
No. These recipes are for backend REST API operations only — site configuration, entity management, and administrative tasks. They do not cover frontend development or displaying data to users.
What business domains do these recipes cover?
The skill covers stores, bookings, payments, CMS, contacts, forms, media, apps, pricing plans, restaurants, rich content, sites, blogs, calendars, domains, and site properties.
Do these recipes handle OAuth authentication with external services like Google Calendar?
Yes. The external calendar integration recipe covers OAuth-based setup with Google Calendar, Microsoft Outlook, and Apple Calendar for bidirectional event sync.

Generated from the current SKILL.md. These answers refresh after source changes.