Services V2 API: Sample Flows

This article provides sample flows focusing on the technical details of managing services using the Services V2 API. These flows demonstrate common integration patterns and can serve as a foundation for your implementation. You can combine different service types with various payment options to meet business needs.

Export new services to an external catalog

If a business manages services in an external catalog, you can periodically export new services from Wix to the external catalog. This ensures that the external system stays synchronized with the latest service information in Wix Bookings.

To export services and maintain synchronization with an external catalog:

  1. For the initial export, call Query Services to retrieve all services. By default, it's 100 for the initial paging limit.

  2. Save the request's date and time to use as a filter in the next query.

  3. Optional: If the response contains 100 services, additional services may exist. Call Query Services again, specifying 100 as paging.offset. Continue retrieving services while increasing the offset, until the system retrieves all services.

  4. Upload the retrieved services to the external catalog.

  5. When it's time for the next export, call Query Services. Save the request's date and time. Specify this filter:

    Copy

  6. Upload the retrieved services to the external catalog.

  7. Repeat steps 5 to 6 for each subsequent export. You may allow business owners to configure the export's time interval.

Create a free class

You can create a class-based service offered at no cost to customers. You could allow customers to book online without requiring the business to individually review and then confirm or decline booking requests. This approach works well for promotional events, community classes, or trial sessions that don't require payment.

To create a free class-based service:

  1. Call Create Service, specifying:

    • The required fields for class-based services:
      • type set to CLASS.
      • name.
      • defaultCapacity set to a value typically higher than 1.
    • Additionally, the following fields needed in this use case:
      • onlineBooking.enabled set to true.
      • onlineBooking.requireManualApproval set to false.
      • payment.rateType set to NO_FEE.
      • payment.options.inPerson set to true even though the service is offered for free.

    For the returned service, save id and schedule.id.

  2. To add class events, call Create Event, specifying:

    • schedule.id from the previous step as event.scheduleId.
    • {"type": "CLASS"}.
    • start.localDate and end.localDate. Learn more about how to set up recurring events.

Customers can now book the free class without any payment required.

Create a fixed price course

You can create a course-based service with a single fixed price for the entire course. To reduce no-show rates, you could require customers to pay upfront online for access to all course events. You could also prevent bookings after the course has started. This approach works well for structured learning programs, workshops, or multi-session training courses.

To create a course-based service that's offered for a standard price:

  1. Call Create Booking Policy, specifying:

    • A policy name.
    • limitLateBookingPolicy.enabled as true.
    • limitLateBookingPolicy.latestBookingInMinutes as 1. This prevents customers from booking the course later than 1 minute before the start of the first course event. Save the policy ID.

  2. Call Create Service, specifying:

    • The required fields for course-based services:
      • type set to COURSE.
      • name.
      • defaultCapacity set to a value typically higher than 1.
    • Additionally, the following fields needed in this use case:
      • bookingPolicy.id set to the value from the previous step.
      • onlineBooking.enabled set to true.
      • payment.rateType set to FIXED.
      • payment.fixed.price.value and optionally a formattedValue.
      • payment.options.online set to true.

    For the returned service, save id and schedule.id.

  3. To add course events, call Create Event, specifying:

    • schedule.id from the previous step as event.scheduleId.
    • {"type": "COURSE"}.
    • start.localDate and end.localDate. Learn more about how to set up recurring events.

Customers can now book the course and pay the standard price when they book online.

Create an appointment service with varied pricing

You could set up a hair cutting service with different prices based on the customer's age with custom variants. For example, a hair cut for adults could cost more than a children's or senior's hair cut. The service would be offered at the main business location with designated staff members.

To create an appointment-based service with varied pricing:

  1. Call Query Staff Members and identify who can provide the service. Save the relevant staff member IDs.

  2. Call List Locations. Save the ID of the location with {"default": true}.

  3. Call Create Service, specifying:

    • The required fields for appointment-based services:
      • type set to APPOINTMENT.
      • name.
      • defaultCapacity set to 1.
      • The schedule.availabilityConstraints.sessionDurations array set to the only supported service duration in minutes. For example, 30 minutes for the hair cut.
    • Additionally, the following fields needed in this use case:
      • All relevant staffMemberIds.
      • A single element in the locations array with {"type": "BUSINESS"} and business.id set to the location ID from the previous step.
      • onlineBooking.enabled set to true.
      • payment.rateType set to VARIED.
      • payment.fixed.price.value and optionally a formattedValue. Depending on the business needs, you can choose either the adult, senior, or children's price as default.
      • At least one of payment.options.inPerson or payment.options.online set to true.

    Save the service ID from the response.

  4. Call Create Service Options And Variants, specifying:

    • The service ID from the previous step.
    • An options.values array with a single option value for all supported customer choices. For the option, specify {"type": "custom"}, its unique option ID in UUID format, customData.name set to age group, and a customData.choices array with the 3 elements child, adult, and senior.
    • A variants.values array with 3 elements: each element specifying the single optionId from above, custom set to either child, adult, or senior, and a corresponding price object with a value and optionally a formattedValue.

Customers can now book appointments and choose from different age group options, each with its corresponding price.

Add pricing plan payment option to an existing service

To expand payment options for an existing service that only accepts online payments, add pricing plan support to provide customers with package-based payment alternatives. This allows customers to purchase class packages or service bundles instead of paying per individual booking.

To add pricing plan payment option to an existing service:

  1. Call Create Plan to create a class package plan, specifying:

    • name set to a descriptive plan name, such as 10-Class Pass.
    • A single object in the pricingVariants array:
      • id set to a unique UUID.
      • name set to a descriptive variant name, such as Single payment.
      • pricingStrategies array with a single flatRate object containing the appropriate amount value.
      • billingTerms object with billingCycle set to null, startType set to ON_PURCHASE, and endType set to UNTIL_CANCELLED.
    • visibility set to PUBLIC, so customers can buy the plan.
    • status set to ACTIVE.

    Save the plan ID from the response.

  2. Call Update Service to enable pricing plan payments, specifying payment.options.pricingPlan set to true.

  3. Call Enable Pricing Plans For Service to add the pricing plan, specifying the plan ID from step 1 in the pricingPlanIds array.

Customers can now book the service using either online payment or the class package plan.

Did this help?