Skip to Content
Account
Enter the email address on your account.
Forgot Your Username?
Enter your password.
Forgot Your Password?

Or continue with

J2Commerce 6

Square Scheduler

13 Min Read

Documentation current for Square Scheduler v6.0.13. Last checked November 18, 2026.

On This Page

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.

  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."}
AttributeWhat It DoesDefaultOptions
serviceOffers only these services. Separate several service IDs with commas.The default services chosen in the pluginUp to 10 IDs of letters, numbers, hyphens and underscores
daysHow many days ahead visitors can book.Days Ahead setting3 to 30
titleHeading shown above the calendar.NoneText, up to 120 characters
introShort text shown under the heading.NoneText, 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

SettingWhat It DoesDefaultOptions
Connection StatusA live check of your Square account, run each time the form opens. Test Connection refreshes it.NoneRead only
Square EnvironmentWhich Square account the calendar uses. Each environment keeps its own credentials, location, services and team members.SandboxSandbox, Production
Connection MethodHow the plugin signs in to Square.Access TokenAccess Token, Connect with Square (OAuth)
Production Access TokenYour live Square access token. Shown for Production with Access Token.EmptyUp to 2048 characters
Sandbox Access TokenYour Square sandbox access token. Shown for Sandbox with Access Token.EmptyUp to 2048 characters
Production Application ID, Production Application SecretFrom the live app's OAuth page. Shown for Production with OAuth.EmptyText
Sandbox Application ID, Sandbox Application SecretFrom the sandbox app's OAuth page. Shown for Sandbox with OAuth.EmptyText
Redirect URLThe address to paste into the Redirect URL box on the Square app's OAuth page. Read only.Your site's callback addressRead only
Square Sign-InThe Connect to Square and Disconnect buttons.NoneButtons

Booking Defaults

SettingWhat It DoesDefaultOptions
Production Location, Sandbox LocationThe Square location whose calendar visitors book into.EmptyLocations in your account
Production Default Services, Sandbox Default ServicesServices 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 MembersOnly show times for these people.Empty (everyone who is bookable)Team members in your account
Service Choice StyleHow 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 ButtonsRadio Buttons, Select Field
Days AheadHow many days into the future visitors can book.143 to 30
Time Slot SpacingThins out the list of times.All Times from SquareAll Times from Square, Every 15 Minutes, Every 30 Minutes, Every Hour
Require Phone NumberMakes the phone number a required part of the booking form.NoYes, No
Show Notes FieldLets visitors add a short note that is saved with the booking.YesYes, No
Confirmation MessageAn extra sentence shown after a booking succeeds.EmptyText
Consent Checkbox TextWhen filled in, visitors must tick a box with this text before booking.EmptyText
CaptchaAsks 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 UseDo Not Use, or an enabled captcha plugin
Show Cancellation PolicyShows your cancellation policy in the details step, above the Book button. See Cancellation Policy.NoYes, No
Require AgreementVisitors must tick a box agreeing to the policy. Shown when Show Cancellation Policy is Yes.NoYes, No
Policy SourceWhere the policy text comes from. Shown when Show Cancellation Policy is Yes.Pull from SquarePull from Square, My Own Text
Custom Policy TextYour own policy text. Shown when the source is My Own Text, and used when Square has no usable policy.EmptyEditor text
Lookup Cache (Minutes)How long the service list, location time zone and cancellation policy are remembered. Available times are never cached.101 to 120

Display

SettingWhat It DoesDefaultOptions
Load Default StylesLoads the plugin stylesheet. Turn it off if your template already styles the calendar through a layout override.YesYes, No
Fallback Contact TextShown instead of the calendar when online booking is unavailable, for example your phone number.EmptyText

Troubleshooting

SettingWhat It DoesDefaultOptions
Debug LogWrites each request to Square and its reply to a log file. See Troubleshooting.NoYes, 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 SeeMeaningFix
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 accountThe account is connected but Appointments is not set up.Set up Appointments in the Square Dashboard.
Appointments Enabled shows Could not be checkedSquare did not answer the Appointments check.Click Test Connection again.
Save the connection firstA 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 SquareSquare 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 SeeMeaningFix
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.

Related Products

Related Products

Still stuck? Our team can help.

Back to Top