---
title: "Square Scheduler"
description: "Square Scheduler is a Joomla system plugin that shows a live Square Appointments booking calendar inside an article or a module. Visitors choose a service, a day and a time, enter their details and…"
url: "https://docs.j2commerce.com/v6/apps-and-extensions/plugins/squarescheduler"
markdown_url: "https://docs.j2commerce.com/v6/apps-and-extensions/plugins/squarescheduler.md"
last_updated: "2026-11-18T23:31:22+00:00"
version: "J2Commerce 6"
breadcrumbs:
  - title: "Home"
    url: "https://docs.j2commerce.com/"
  - title: "J2Commerce 6"
    url: "https://docs.j2commerce.com/v6"
  - title: "Apps and Extensions"
    url: "https://docs.j2commerce.com/v6/apps-and-extensions"
  - title: "Plugins"
    url: "https://docs.j2commerce.com/v6/apps-and-extensions/plugins"
  - title: "Square Scheduler"
    url: "https://docs.j2commerce.com/v6/apps-and-extensions/plugins/squarescheduler"
---

# Square Scheduler

Square Scheduler is a Joomla system plugin that shows a live Square Appointments booking calendar inside an article or a module. Visitors choose a service, a day and a time, enter their details and book without leaving your site.

It connects to your Square account with OAuth or a personal access token and does not need J2Commerce.

## Requirements

- Joomla 6.x.
- A Square account with Square Appointments turned on, and at least one bookable service.
- For OAuth: a Square Developer app with an Application ID and Application Secret.
- For a personal access token: a token from the Square Developer Dashboard. Creating bookings with a token needs a Square Appointments Plus or Premium subscription. OAuth bookings also work on the free Appointments plan.

---

## Installation

Buy and download it from [Square Scheduler on the J2Commerce Extensions Store](https://www.j2commerce.com/extensions/general-plugins/square-scheduler).

1. In Joomla, open **System** -> **Install** -> **Extensions** and upload the plugin package.
2. Open **System** -> **Plugins** and search for **Square Scheduler**.
3. Make sure the plugin is enabled, then open it.

---

## Connecting Square

The plugin keeps two separate sets of credentials, location, services and team members: one for **Sandbox** and one for **Production**. Switching **Square Environment** never overwrites the other set.

Sandbox is Square's practice account. Production takes real bookings.

Open the **Connection** tab, choose **Square Environment**, then choose a **Connection Method**.

### Connect with Square (OAuth)

1. In the Square Developer Dashboard, open your app and its **OAuth** page. Use a Sandbox app for the Sandbox environment and a live app for Production.
2. In the plugin, set **Connection Method** to **Connect with Square (OAuth)**.
3. Copy the address shown in **Redirect URL** and paste it into the Redirect URL box on the app's OAuth page. It must match exactly.
4. Copy the **Application ID** and **Application Secret** from the OAuth page into the plugin fields for the chosen environment.
5. Click **Save**. **Connect to Square** stays disabled until the ID and secret are saved.
6. Click **Connect to Square**, sign in to Square and approve the access it asks for.

Back in Joomla, the message **Connected to Square.** appears. The plugin shows the merchant and the date the sign-in currently runs until. The sign-in renews itself.

Click **Disconnect** to end the connection. Online booking stops until you connect again.

The app asks Square for these permissions: Appointments read and write, Customers read and write, Items read and Merchant Profile read.

The Redirect URL has this form, with your own site address at the start:

```
https://example.com/administrator/index.php?option=com_ajax&group=system&plugin=squarescheduler&format=raw&task=oauthCallback
```

> **Important:** Keep the Application Secret and any access token private. Anyone who holds them can act as your Square account. The Application Secret is not an access token.

### Connect with an Access Token

1. In the Square Developer Dashboard, copy the access token for the environment you chose.
2. In the plugin, set **Connection Method** to **Access Token**.
3. Paste the token into **Production Access Token** or **Sandbox Access Token**, whichever shows.
4. Click **Save**.

### Test the Connection

Click **Test Connection**. **Connection Status** shows these lines:

- **Connected**: Yes or No.
- **Account**: your business name.
- **Environment**: Sandbox or Production, shown in your interface language.
- **Time Zone**: the location's time zone.
- **Appointments Enabled**: Yes, No, or **Could not be checked**.
- **Bookable Services**: the number of services visitors can book.

Screen readers announce the result of **Test Connection**, including a warning when Square Appointments is not enabled.

---

## Choosing Location, Team, and Services

Open the **Booking Defaults** tab. The lists load from Square, so save the connection first. The fields shown follow the environment you chose.

1. Pick the **Production Location** (or **Sandbox Location**). Visitors book into this location's calendar. Location IDs differ between sandbox and production.
2. Under **Production Default Services** (or **Sandbox Default Services**), click the add button and pick a service for each row. Drag rows to reorder them; the first service is shown first. Leave the list empty to offer every bookable service.
3. Optional: under **Production Team Members** (or **Sandbox Team Members**), pick the people whose times should show. Leave it empty for everyone who is bookable.

> **Note:** Until a location is chosen and credentials are saved, the calendar does not show. Anyone who can edit the plugin sees a yellow message that says Square Scheduler is not connected yet. Other visitors see nothing.

---

## Adding the Calendar

### The Tag

Put the `{squarescheduler}` tag in the text of an article where the calendar should appear. In any other place the tag is removed and nothing shows.

```
{squarescheduler}
{squarescheduler service=ABC123,DEF456 days=21 title="Book a Visit" intro="Pick a time that suits you."}
```

| Attribute | What It Does | Default | Options |
| --- | --- | --- | --- |
| **service** | Offers only these services. Separate several service IDs with commas. | The default services chosen in the plugin | Up to 10 IDs of letters, numbers, hyphens and underscores |
| **days** | How many days ahead visitors can book. | Days Ahead setting | 3 to 30 |
| **title** | Heading shown above the calendar. | None | Text, up to 120 characters |
| **intro** | Short text shown under the heading. | None | Text, up to 300 characters |

Put a value that contains spaces in double quotes. Other attributes are ignored.

### The Companion Module

The companion module, `mod_squarescheduler`, shows the same calendar in a module position. It uses the plugin's connection and Booking Defaults, so the plugin must be enabled and connected. Create it under **Content** -> **Site Modules**.

---

## Settings

### Connection

| Setting | What It Does | Default | Options |
| --- | --- | --- | --- |
| **Connection Status** | A live check of your Square account, run each time the form opens. **Test Connection** refreshes it. | None | Read only |
| **Square Environment** | Which Square account the calendar uses. Each environment keeps its own credentials, location, services and team members. | Sandbox | Sandbox, Production |
| **Connection Method** | How the plugin signs in to Square. | Access Token | Access Token, Connect with Square (OAuth) |
| **Production Access Token** | Your live Square access token. Shown for Production with Access Token. | Empty | Up to 2048 characters |
| **Sandbox Access Token** | Your Square sandbox access token. Shown for Sandbox with Access Token. | Empty | Up to 2048 characters |
| **Production Application ID**, **Production Application Secret** | From the live app's OAuth page. Shown for Production with OAuth. | Empty | Text |
| **Sandbox Application ID**, **Sandbox Application Secret** | From the sandbox app's OAuth page. Shown for Sandbox with OAuth. | Empty | Text |
| **Redirect URL** | The address to paste into the Redirect URL box on the Square app's OAuth page. Read only. | Your site's callback address | Read only |
| **Square Sign-In** | The **Connect to Square** and **Disconnect** buttons. | None | Buttons |

### Booking Defaults

| Setting | What It Does | Default | Options |
| --- | --- | --- | --- |
| **Production Location**, **Sandbox Location** | The Square location whose calendar visitors book into. | Empty | Locations in your account |
| **Production Default Services**, **Sandbox Default Services** | Services offered when a tag does not choose its own. Drag the rows to reorder them. | Empty (every bookable service) | Services in your account |
| **Production Team Members**, **Sandbox Team Members** | Only show times for these people. | Empty (everyone who is bookable) | Team members in your account |
| **Service Choice Style** | How visitors pick a service. Radio Buttons shows one button per service and suits a few services. Select Field shows one drop-down list and suits many. | Radio Buttons | Radio Buttons, Select Field |
| **Days Ahead** | How many days into the future visitors can book. | 14 | 3 to 30 |
| **Time Slot Spacing** | Thins out the list of times. | All Times from Square | All Times from Square, Every 15 Minutes, Every 30 Minutes, Every Hour |
| **Require Phone Number** | Makes the phone number a required part of the booking form. | No | Yes, No |
| **Show Notes Field** | Lets visitors add a short note that is saved with the booking. | Yes | Yes, No |
| **Confirmation Message** | An extra sentence shown after a booking succeeds. | Empty | Text |
| **Consent Checkbox Text** | When filled in, visitors must tick a box with this text before booking. | Empty | Text |
| **Captcha** | Asks visitors to pass a captcha before **Book This Time** creates a booking. The list shows the captcha plugins that are enabled; set one up under Plugins first. If you limit that captcha plugin to some access groups, visitors outside those groups still have to pass it, so keep its access set to Public. | Do Not Use | Do Not Use, or an enabled captcha plugin |
| **Show Cancellation Policy** | Shows your cancellation policy in the details step, above the Book button. See [Cancellation Policy](https://docs.j2commerce.com/v6/apps-and-extensions/plugins/squarescheduler#cancellation-policy). | No | Yes, No |
| **Require Agreement** | Visitors must tick a box agreeing to the policy. Shown when **Show Cancellation Policy** is Yes. | No | Yes, No |
| **Policy Source** | Where the policy text comes from. Shown when **Show Cancellation Policy** is Yes. | Pull from Square | Pull from Square, My Own Text |
| **Custom Policy Text** | Your own policy text. Shown when the source is My Own Text, and used when Square has no usable policy. | Empty | Editor text |
| **Lookup Cache (Minutes)** | How long the service list, location time zone and cancellation policy are remembered. Available times are never cached. | 10 | 1 to 120 |

### Display

| Setting | What It Does | Default | Options |
| --- | --- | --- | --- |
| **Load Default Styles** | Loads the plugin stylesheet. Turn it off if your template already styles the calendar through a layout override. | Yes | Yes, No |
| **Fallback Contact Text** | Shown instead of the calendar when online booking is unavailable, for example your phone number. | Empty | Text |

### Troubleshooting

| Setting | What It Does | Default | Options |
| --- | --- | --- | --- |
| **Debug Log** | Writes each request to Square and its reply to a log file. See [Troubleshooting](https://docs.j2commerce.com/v6/apps-and-extensions/plugins/squarescheduler#troubleshooting). | No | Yes, No |

---

## Cancellation Policy

Set **Show Cancellation Policy** to Yes to show a **Cancellation Policy** block above the Book button. Then choose a **Policy Source**.

- **Pull from Square** shows the policy text from your Square Appointments settings. If that is empty, it builds a sentence from Square's cancellation window and fee. If Square has nothing usable, your **Custom Policy Text** is shown instead.
- **My Own Text** shows your **Custom Policy Text**. Basic formatting is kept. If you have never saved a custom text, a default sentence about cancelling at least 1 day ahead is shown.

Set **Require Agreement** to Yes to add the checkbox **I have read and agree to the cancellation policy**. Visitors cannot book until it is ticked. If no policy text is available, booking is never blocked.

---

## How Visitors Book

1. If there is more than one service, the visitor picks one under **Choose a Service**.
2. The visitor picks a day under **Choose a Day** and a time under **Choose a Time**. A line under the heading says which time zone the times are shown in.
3. The visitor enters **Full Name**, **Email** and, depending on your settings, phone, note, consent and policy agreement under **Your Details**.
4. If you chose a **Captcha**, the visitor completes it.
5. The visitor clicks **Book This Time**.

A confirmation, **You Are Booked**, replaces the form with the appointment time and a reference number. Square creates the booking and a customer record with the visitor's name, email and phone.

A visitor can make 3 bookings in 10 minutes. After that the form asks them to wait and try again. Field errors name the field and move focus to it. When more than one field needs attention, the form announces how many. The page never moves keyboard focus on its own when it loads.

The calendar and its messages are translated into Arabic, Danish, Dutch, Finnish, French, German, Greek, Hebrew, Italian, Japanese, Norwegian Bokmål, Persian, Polish, Portuguese (Brazil and Portugal), Russian, Spanish, Swedish, Traditional Chinese and Turkish.

---

## Template Override

To change the markup of the calendar, copy the layout into your template:

```
plugins/system/squarescheduler/layouts/squarescheduler/calendar.php
templates/YOUR_TEMPLATE/html/layouts/squarescheduler/calendar.php
```

Your copy wins over the plugin's own file. Keep the `data-sqs` attributes and field names from the original, because the booking script finds everything through them.

Keep the hidden form token input and the captcha block exactly as they are. Set **Load Default Styles** to No if your template supplies the styling.

---

## Troubleshooting

### Test Connection Messages

| What You See | Meaning | Fix |
| --- | --- | --- |
| Not connected yet. Add your credentials, save, and the status appears here. | No credentials are saved for the chosen environment. | Add a token, or connect with OAuth, then save. |
| Square rejected these credentials. Check the environment and token, then save again. | Square answered 401. | Check that **Square Environment** matches the token or app. Paste the token again, or reconnect with OAuth. |
| Square could not be reached or returned an error. Try again in a moment. | Any other error from Square, or no reply. | Click **Test Connection** again. Turn on **Debug Log** to see the code. |
| Square Appointments isn't turned on for this Square account | The account is connected but Appointments is not set up. | Set up Appointments in the Square Dashboard. |
| Appointments Enabled shows Could not be checked | Square did not answer the Appointments check. | Click **Test Connection** again. |
| Save the connection first | A location, service or team list has no credentials to load from. | Save the Connection tab, then reopen the plugin. |
| Could not load the list from Square | Square returned an error while loading the list. | Click **Test Connection**, then reopen the plugin. |
| Enter the Application ID and Secret and save the plugin first. | OAuth fields are empty or not saved. | Fill in both, save, then click **Connect to Square**. |
| Square did not complete the sign-in. Check the Application ID, the secret and the Redirect URL, then try again. | The OAuth sign-in failed or was cancelled. | Check that the Redirect URL on the Square app matches the plugin exactly, and that the ID and secret belong to the same environment. |

### Visitor Messages

| What You See | Meaning | Fix |
| --- | --- | --- |
| Online booking is not available right now. Please contact us to book. | The calendar could not reach Square, or no service can be booked. | Check **Connection Status** and the chosen services. Fill in **Fallback Contact Text** so visitors see how to reach you. |
| That time was just taken. Please choose another. | Someone else booked the slot first. | The visitor picks another time. |
| Too many attempts. Please wait a few minutes and try again. | The booking limit of 3 in 10 minutes was reached. | Wait and try again. |
| Your session expired. Please reload the page and try again. | The form token is no longer valid. | Reload the page. |
| Something went wrong on our side. Please try again in a few minutes or contact us. | Square returned an error. | Turn on **Debug Log** and read the reply. |

### The Calendar Does Not Show

- Check that the plugin is enabled, a location is chosen and **Connection Status** says **Connected**.
- Check that the tag is in an article. In lists, category blogs and search results it is removed.
- Check that the chosen services are offered at the chosen location. Other services are hidden.

### Page Cache and Lookup Cache

The calendar works with Joomla page caching on. Available times are always read live from Square.

The service list, time zone and cancellation policy are remembered for the number of minutes in **Lookup Cache (Minutes)**. Click **Test Connection** to clear them after you change something in Square.

### Debug Log

Set **Debug Log** to Yes to write every request to Square and its reply to this file:

```
administrator/logs/squarescheduler-debug.log.php
```

Access tokens, secrets, card data, email addresses and other contact details are masked, and long replies are cut at 2 KB. Turn the log off when you are done.

---

## Uninstalling

1. If you used OAuth, open the plugin and click **Disconnect**.
2. Remove the `{squarescheduler}` tag from your articles and unpublish or delete any companion module.
3. Open **System** -> **Install** -> **Manage**, search for **Square Scheduler** and uninstall it.
4. Delete the debug log file if it exists.
