> For the complete documentation index, see [llms.txt](https://help.peoplevine.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.peoplevine.com/products/integrations-overview/book4time-setup.md).

# Book4Time — Operator Manual

> **Walkthrough (Peoplevine × Book4Time):** [Watch here](https://www.loom.com/share/9fc8c8db38bb47de91c931bb6a624687)

### Before you begin (Prerequisites)

* **Peoplevine permissions**: You must be an **Administrator** or **Supervisor** to configure integration settings in the Control Panel. See: [How to Manage Users and Permissions](/products/control-panel-overview/admin-overview/manage-roles-permissions.md).
* **Book4Time account** with API access enabled for membership requests. Ask your Book4Time representative to approve API tokens for membership.
* **Five credentials** from your Book4Time rep and API admin:
  * **API Token** and **Account Token** (from your Book4Time rep)
  * **API Login ID**, **Password**, and **Login URL** (API user credentials)
* Access to both **Book4Time Admin** and the **Peoplevine Control Panel**.
* A Book4Time **tender type** for Peoplevine payments (created during setup — see Connect guide).
* At least one payment processor connected in Peoplevine with the **3rd Party Spa/Activity Integrations** slot assigned. See: [How to Link a Payment Processor](/products/control-panel-overview/admin-overview/link-payment-processor.md).
* If using tier-based pricing, membership program SKUs in Peoplevine must match membership IDs in Book4Time (case-sensitive, character-for-character).

> For full setup instructions including Book4Time-side configuration (tender types, online booking management, webhooks, and field mapping), see [Connect Book4Time and Peoplevine](https://docs.peoplevine.com/peoplevine-docs/peoplevine-connect) in Peoplevine Connect.

***

### Setup

The steps below cover Peoplevine Control Panel configuration only. Book4Time-side setup (tender types, online booking management settings, webhooks) is covered in the Connect guide linked above.

1. Click the **\[Company Name]** dropdown in the top-left corner and navigate to [**Integrations > Integrated Platforms**](https://control.peoplevine.com/admin_authenticate.aspx).

> **Note (Pro Dash):** Navigate to **AUTOMATE > Integrated Platforms**.

2. Under **Reservations**, select **Book4Time**.
3. In **Associate with Location**, select the Peoplevine directory location for this connection.
4. In **Connect Through**, select **v2**.
5. In **API Location**, select the Book4Time datacenter matching your account region (North America, Europe and Middle East, or Asia Pacific).
6. Enter your **API Token** and **Account Token**.
7. Click **VALIDATE CREDENTIALS**.
8. Open the connection and click **EDIT**.
9. Under **Credentials to Authenticate API**, enter the **Login ID**, **Password**, and **Login URL**.
10. Enable **Enable Webhooks** and copy the generated webhook URL — you will need this for Book4Time webhook setup (see the Connect guide).
11. Under **Settings**, configure the location mapping:

| Setting               | What to enter                                        |
| --------------------- | ---------------------------------------------------- |
| **Location**          | Book4Time location ID                                |
| **Member Guest Type** | Peoplevine member type ID                            |
| **Hotel Guest Type**  | Temporary guest type ID (if used)                    |
| **Request Type**      | Default request type for bookings                    |
| **Member Group**      | Customer group for synced members                    |
| **Customer Group**    | Customer group for hotel guests or cancelled members |
| **Cancel Reason**     | Default cancel reason ID                             |

12. Under **Setup Member Payment-On-File**, map tender types:

| Tender                         | Payment cascade                                   |
| ------------------------------ | ------------------------------------------------- |
| **Tender Type Auto**           | Credits, then payment on file, then house account |
| **Tender Type Member Account** | Payment on file, then house account               |
| **Tender Type House Account**  | Always closes to house account                    |

13. Under **Sync Transactions At**, select the local hour the daily transaction sync runs (hour, minute, AM/PM). Each connection runs one transaction sync per day at its configured hour. Set it to a time after your registers close — a later local-morning hour such as 10 AM is a safe choice — so all of the day's transactions are captured.
14. Click **UPDATE CONNECTION**.

***

### Day-to-Day: Front of House

#### Member recognition

* New members created in Peoplevine sync to Book4Time automatically.
* Membership status changes in Peoplevine update Book4Time in real time. Only active memberships sync.
* Book4Time supports one active membership at a time. Primary membership takes priority; if none is primary, the oldest active membership wins.

#### Member booking (portal)

* Members can check availability, book, and cancel spa appointments from the Member Portal. To modify an existing appointment, members cancel and re-book.
* Appointments sync bi-directionally (requires webhooks configured during setup).
* Spa services imported from Book4Time appear as inactive schedulers under [**SELL > All Schedulers**](https://control.peoplevine.com/schedulers) — activate them manually after review.

#### Viewing upcoming appointments

1. Navigate to [**SELL > All Schedulers**](https://control.peoplevine.com/schedulers).

> **Note (Pro Dash):** Navigate to **SELL > Schedulers**.

2. Filter by **Type: Spa** and **Status: Active Only**, then click **APPLY**.
3. Click on the service to open the scheduler detail page. The **RECENTLY BOOKED SLOTS** section at the bottom shows upcoming bookings. Click **VIEW ALL BOOKED SLOTS** to see the full list.

> You can also view a specific member's appointments from their CRM profile under the **APPOINTMENTS** section.

#### Charging a member for a guest appointment

When a member pays for a guest's appointment at checkout, the spa staff selects the **Peoplevine Payment on File** tender and enters the member's ID when prompted. The charge posts to the member's account.

> Peoplevine tenders do not support split payments.

See the Connect guide for full steps and screenshots.

#### Charging a non-member / walk-in guest

When a non-member is charged via the Peoplevine tender in Book4Time, Peoplevine creates an invoice in PV under a **Walk-in** customer record. Manage these invoices via the standard Walk-in invoice flow.

#### Payment tenders

Staff close checks in Book4Time using Peoplevine tender types:

| Tender             | What happens in Peoplevine                                   |
| ------------------ | ------------------------------------------------------------ |
| **Auto**           | Uses credits first, then payment on file, then house account |
| **Member Account** | Payment on file, then house account                          |
| **House Account**  | Always closes to house account                               |

#### Taking payment in Book4Time (full workflow)

1. **Check in** — find the appointment in Book4Time, right-click, select **Check-in**, confirm.
2. **Check out** — after the service, right-click the appointment, select **Check-out**, click **Payment**.
3. **Apply the Peoplevine tender** — select the correct tender (e.g., Peoplevine Payment on File or Peoplevine House Account), confirm the amount, click **Accept**, then **Finish**. If charging someone other than the checked-in member, enter their Peoplevine customer number when prompted.
4. **Close the register** — go to **Cash drawer management > Register summary**, click **Close register**, and complete the approval prompts.

> Book4Time transactions sync into Peoplevine on the daily transaction sync — once per day at the hour set in **Sync Transactions At** (configured for after your registers close). Transactions from a closed register are picked up on the next scheduled sync.

> For a step-by-step visual guide with screenshots, see: [Taking payments in B4T with Peoplevine tenders](https://scribehow.com/viewer/Taking_payments_in_B4T_with_Peoplevine_tenders__zftcA8h6Qt2TGBu_QZed-w).

***

### Day-to-Day: Finance

#### Dual-order pattern (Booking Order vs Sales Order)

When a member books through the Member Portal, Peoplevine creates a **Booking Order** (reservation record). When the spa later checks out that appointment in Book4Time, Peoplevine creates a separate **Sales Order** (paid transaction).

These are intentionally two separate orders — they should NOT be merged. The final checkout can differ from the original booking due to added items, taxes, discounts, tips, or date changes, and matching IDs cross-system is unreliable. **Only Sales Orders count toward revenue.**

> If staff or finance see what looks like "double orders" for one appointment, this is expected behaviour — not a duplicate charge.

#### Payment processing

Book4Time charges are not processed in real time — they are processed the next day. If a charge fails, it generates an invoice in Peoplevine.

#### Processor routing

Book4Time charges route to the **3rd Party Spa/Activity Integrations** processor slot.

#### Void and refund rules

Book4Time orders sync to Peoplevine on the **daily transaction sync** — once per day at the hour set in **Sync Transactions At**, after the business day closes — not in real time.

**Same-day refund (before the order syncs):** If the refund is processed in Book4Time before that day's transaction sync runs, no order or transaction is created in Peoplevine. Nothing needs to be done on the Peoplevine side.

**Next-day refund (after the order has synced):** If the order has already synced to Peoplevine on a prior daily sync, issue the refund in Book4Time. On the **next daily sync**, Peoplevine automatically receives the refund. No manual action is needed in Peoplevine.

> **Important**: Always initiate refunds in Book4Time, not in Peoplevine. The refund syncs automatically on the next daily sync.

> For processing refunds in Peoplevine (full, partial, and across payment processors), see [How to Process a Refund](/products/control-panel-overview/refunds-adjustments-overview/process-refund.md).

***

### What Gets Synced

| Data                                                    | Direction              | Timing                                               |
| ------------------------------------------------------- | ---------------------- | ---------------------------------------------------- |
| Member profiles (name, email, phone, address, birthday) | Peoplevine → Book4Time | On creation and updates                              |
| Membership status and tier                              | Peoplevine → Book4Time | Real-time (active memberships only)                  |
| Appointments (book and cancel)                          | Both directions        | When booked or cancelled (requires webhooks)         |
| Availability                                            | Book4Time → Peoplevine | Real-time (shown live in the portal)                 |
| Payments (post-pay)                                     | Book4Time → Peoplevine | At appointment checkout                              |
| Spa services                                            | Book4Time → Peoplevine | On import (one-time; schedulers inactive by default) |

> **Marketing email/SMS consent is not synced between Peoplevine and Book4Time.** Each platform manages its own marketing preferences — set them separately in Peoplevine and in Book4Time. Peoplevine continues to sync member profile details, but it does not influence marketing enrolment in Book4Time.

> Full field mapping (Peoplevine → Book4Time) is available in the Connect guide.

***

### Troubleshooting

**Bookings not syncing from Book4Time to Peoplevine:** Webhooks are not configured or are pointing to the wrong URL. Verify you created both Appointment Add and Appointment Update webhooks in Book4Time with the correct Peoplevine webhook URL. See the Connect guide for webhook setup.

**Member not receiving tier pricing on spa services:** The membership SKU in Peoplevine does not match the membership ID in Book4Time. Compare them in both systems — they must match exactly, including case.

**"Two orders" appearing for one appointment:** This is expected. The portal booking creates a Booking Order, and the Book4Time checkout creates a Sales Order. These are intentionally separate — see Day-to-Day: Finance above.

**Login credentials changed — sync stopped:** If the Book4Time Login ID, Password, or Login URL changes, you must update it in every Peoplevine connection. If you miss one, syncing will fail for that location.

**Decline with "Only Stripe Connect platforms can work with other accounts":** This Stripe error appears when a B4T transaction is routed to a Stripe account that is not configured as a Stripe Connect platform. The `client_id` parameter may be incorrect or the Connect setup is incomplete. Contact Peoplevine Support to verify the Stripe Connect configuration.

**Payments not processing — no tender type found:** The Peoplevine tender type must be created and enabled per location in Book4Time Admin. Verify it is active under Admin > Account Management > Locations > Tender Setup.

**Previously saw duplicate profiles or duplicate Member Portal bookings:** New duplicates should no longer be generated. Existing duplicates from prior bugs may need manual cleanup; contact support if cleanup is required.

***

### Best Practice

* **Never create new member profiles in Book4Time** — if you can't find a member in Book4Time, push them from Peoplevine first. Creating profiles directly in Book4Time causes duplicate records and sync issues.
* **Match membership SKUs exactly** — the Peoplevine membership SKU must match the Book4Time membership ID character-for-character (case-sensitive). A mismatch means no tier discount. *(Connect guide)*
* **Set Book4Time membership programs to permanent** (no expiry). Peoplevine manages membership lifecycle. *(Connect guide)*
* **Coordinate tender types with Book4Time before go-live.** The Peoplevine tender type in Book4Time must be enabled per location (Admin > Account Management > Locations > Tender Setup). *(Connect guide)*
* **Update Online Booking Management settings** in Book4Time — these toggles are the most common blocker for bookings. See the Connect guide for the exact settings. *(Connect guide)*

*Last updated: 2026-06-12*


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://help.peoplevine.com/products/integrations-overview/book4time-setup.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.