Widget Reference Guide

Product Overview

PCOWidget is a self-contained, embeddable calendar that pulls live event data from your Planning Center Online calendar and renders it as an interactive, styled component on any web page — with a single <script> tag.

How It Works

PCOWidget sits between your church website and Planning Center. Your site never touches PCO credentials — they live encrypted on PCOWidget's servers.

Your Church Website (Squarespace, WordPress, Wix, HTML)
    <script src="https://api.pcowidget.com/v1/calendar-widget.js?key=YOUR_KEY">
                              ↓
                    api.pcowidget.com
                              ↓
    Your API key → your PCO credentials (encrypted, server-side)
                              ↓
           api.planningcenteronline.com/calendar/v2
                              ↓
    Events rendered as HTML → injected into your page

1. Your <script> tag loads the widget JavaScript from PCOWidget's API servers
2. The widget auto-detects its endpoint from its own src URL
3. PCOWidget's PHP middleware authenticates with Planning Center using your encrypted credentials (never exposed to visitors)
4. Events are fetched, formatted, and returned as styled HTML
5. Month navigation and view switching fetch lightweight HTML fragments — no full page reload

Embedding the Widget

Basic Embed

One line. That's it. Paste into any HTML page, Squarespace Code Block, or WordPress Custom HTML block:

<script src="https://api.pcowidget.com/v1/calendar-widget.js?key=YOUR_KEY"></script>

Squarespace

Add a Code Block (not a Markdown block) and paste your script tag. No <html>, <head>, or <body> tags needed — the widget handles everything.

.sqs-code-container {
  display: block;
  width: 100%;
}

WordPress

Add a Custom HTML block in the Gutenberg editor and paste the script tag.

Mounting Into an Existing Element

If you already have a container div where you want the widget, use data-target:

<div id="my-calendar"></div>
<script src="https://api.pcowidget.com/v1/calendar-widget.js?key=YOUR_KEY"
        data-target="my-calendar"></script>

Multiple Instances on One Page

Each <script> tag creates an independent widget instance. Configure each with different data-* attributes:

<!-- Full church calendar -->
<script src="https://api.pcowidget.com/v1/calendar-widget.js?key=YOUR_KEY"
        data-layout="table"></script>

<!-- Youth events sidebar -->
<script src="https://api.pcowidget.com/v1/calendar-widget.js?key=YOUR_KEY"
        data-tag="Youth"
        data-layout="list"></script>

<!-- This week's services (homepage) -->
<script src="https://api.pcowidget.com/v1/calendar-widget.js?key=YOUR_KEY"
        data-layout="simple"
        data-this-week="1"
        data-title="This Week's Services"></script>

Data Attributes

Control each widget instance using data-* attributes on the <script> tag:

Quick Reference Table

Boolean Values — Accepted Formats

The boolean attributes (data-featured, data-this-week, data-allow-week-nav, data-include-past, data-hide-end-time, and data-campus-untagged) are flexible about how you write true or false. All of the following are valid:

Examples — these are all equivalent:

<!-- All three turn on data-this-week -->
<script src="..." data-this-week="1"></script>
<script src="..." data-this-week="true"></script>
<script src="..." data-this-week="TRUE"></script>

<!-- All three turn on data-include-past -->
<script src="..." data-include-past="true"></script>
<script src="..." data-include-past="True"></script>
<script src="..." data-include-past="1"></script>

Layouts

Choose from six layouts, each designed for a different use case:

Month Grid — data-layout="table"

Full monthly calendar grid (Sunday–Saturday). Shows day numbers with event indicators.

• Desktop: Event name and time visible inside grid cells
• Mobile (<768px): Colored dot indicators instead of event text
• Includes month/year header with prev/next month arrows and a view-switching toolbar
• Click any event to open the full-detail popover

<script src="https://api.pcowidget.com/v1/calendar-widget.js?key=YOUR_KEY"
        data-layout="table"></script>

Week Strip — data-layout="week"

Compact 7-day view extracted from the month grid. Shows only the row containing today (or the first row with events for non-current months). Ideal for sidebars or "this week" widgets.

<script src="https://api.pcowidget.com/v1/calendar-widget.js?key=YOUR_KEY"
        data-layout="week"></script>

List — data-layout="list"

Compact row-based layout with thumbnail images (or date badges when no image). Shows event name, date, time, and location. Stacks on mobile. Good for ministry landing pages with moderate detail.

<script src="https://api.pcowidget.com/v1/calendar-widget.js?key=YOUR_KEY"
        data-layout="list"
        data-tag="Women's Ministry"></script>

Cards — data-layout="cards"

Rich card grid — auto-fit responsive layout. Each card is at least 260px wide; columns fill all available space naturally (typically 2 on tablet, 3+ on wide desktop, 1 on mobile). Each card shows:

• 16:9 image (or date badge placeholder)
• Date badge, title, time, description (3-line clamp), location
• Tag color badges
• "View Details" link
• Featured events get accent borders and star indicators

<!-- Featured events showcase -->
<script src="https://api.pcowidget.com/v1/calendar-widget.js?key=YOUR_KEY"
        data-layout="cards"
        data-featured="1"
        data-shadow="burgundy"></script>

Image Tiles New – data-layout="tiles"

A compact image grid that sits between simple (text only) and cards (large and detailed). Each tile is about a third the height of a card: the event's image, its name on up to two lines, and the date and time. Built for churches that want a dense, visual "what's on" block instead of a long scroll of full cards.

Choose your grid. data-columns sets how many tiles go across, from 1 to 8, and defaults to 4. data-rows sets how many rows deep it goes. Together they give you an exact block: data-columns="5" with data-rows="2" is always ten events, no matter how busy the month is. Leave data-rows off and it shows everything. On smaller screens the grid steps down to 3 across, then 2, so tiles never shrink into illegibility.

<script src="https://api.pcowidget.com/v1/calendar-widget.js?key=YOUR_KEY"
        data-layout="tiles"
        data-columns="5"
        data-rows="2"></script>

Events without a picture still look right. Not every event in Planning Center has artwork, and on some calendars most of them do not. Those tiles get a coloured panel with a small calendar icon rather than a blank or broken image. The colour comes from the event's name, so the same event always looks the same and the grid stays varied instead of repetitive.

Clicking opens the full event. Click or tap a tile and the complete event card opens in the middle of the screen, with the large image, description, tags, location, and the "View Details", "Register", and "Add to Calendar" buttons. It works from the keyboard with Tab and Enter. Press Escape or click outside to close.

If you would like a tile to open when the pointer rests on it as well, add data-hover-preview="1". It waits for a brief pause first, so moving the mouse across the grid on the way somewhere else does not flash a card for every tile it passes over. Tapping on a phone opens the card either way, since phones have no hover.

Simple Tiles — data-layout="simple"

Minimal clickable service-time tiles. Each tile shows a clock icon, event name, sermon title (if set), date, and time range. Clicking a tile opens the full event popover. No toolbar — clean and focused.

Designed for use with data-this-week="1" to show the current week's events on your homepage or church info page.

Sermon Title Display

Your recurring "Traditional Worship" event stays the same in PCO, but the sermon title changes each week. To surface a sermon title on a simple tile, add a line to the PCO event's Details field:

sermon: Giving Expectantly

• The prefix (sermon:) is stripped — only the title text is shown
• The match is case-insensitive (Sermon:, SERMON:, etc. all work)
• The line can appear anywhere in the Details field
• If no sermon: line is present, the subtitle is omitted — no blank space

Week Navigation

Add data-allow-week-nav="1" to let visitors browse upcoming weeks. The prev button is disabled on the current week. The center label shows "This Week" / "Next Week" / "+N Weeks" and clicking it returns to today.

Column Count

Use data-columns to control tiles per row. If you have 4 services on Holy Week, set data-columns="4". Always collapses to 1 column on mobile. The same attribute now pins the cards layout too, and pairs with data-rows when you want a fixed block of events rather than the whole month.

<script src="https://api.pcowidget.com/v1/calendar-widget.js?key=YOUR_KEY"
        data-layout="simple"
        data-this-week="1"
        data-title="This Week's Services"
        data-tag="Worship Services"
        data-allow-week-nav="1"
        data-nav-align="center"
        data-columns="2"></script>

Feature Flags

Feature flags are server-side controls managed by PCOWidget for your account. They determine which interactive features are enabled in your widget. All are enabled by default on Pro plans.

Styling Your WidgetNew

Every church can match the widget to its website, on every plan. The quickest way is the Widget Display Builder: its Style your widget section has a colour picker and a live preview, and can show the preview on a light, grey or dark page. Each option below is also an attribute you can add by hand. Leave them all off and the widget looks exactly as it always has.

The widget also protects its own buttons from website themes. Page builders such as Elementor style every button on a page, which used to turn the widget’s month and view buttons into the theme’s buttons; they now keep the widget’s look.

A worked example

A navy, square-cornered widget in the site’s own font, sitting directly on the page with no heading of its own:

<script src="https://api.pcowidget.com/v1/calendar-widget.js?key=YOUR_KEY"
        data-layout="tiles"
        data-accent="#4a5a8c"
        data-font="inherit"
        data-frame="none"
        data-corners="square"
        data-text-size="large"
        data-show-title="0"></script>

One colour in, a whole palette out

You choose one colour. The widget works out the rest: a darker shade for hover, a pale tint behind event chips and tags, a text shade that stays readable on white, and black or white text for anything drawn on your colour, whichever reads better. A pale brand colour such as gold therefore still gives legible times and buttons. If you want an exact hover colour, add data-accent-hover.

Your own CSS

You can still restyle the widget further with your own CSS: every widget class starts with pcow-. On the free Starter plan, the small “Powered by PCOWidget” line must stay visible. It takes on your brand colour when you set one, so it fits your page. Removing it is part of the Pro plan; see The Starter credit in our Terms.

Shadow Presets

Set the container shadow tone with data-shadow:

CSS Isolation

All widget CSS classes are prefixed with pcow-. Widget styles will not conflict with your site's existing CSS, even on Squarespace, WordPress, or Wix where host-site styles are aggressive.

Tag Colors

When tag color coding is enabled, events are automatically colored by their Planning Center tag. No configuration needed — the widget reads the tag name and applies the matching style.

Tags not in the default map receive the standard blue styling. Additional tag color mappings can be configured on your account — contact support to request custom tag colors.

Multi-Campus ChurchesNew

If your church has more than one campus, data-campus lets each campus page show only its own events, all from the one Planning Center calendar you already keep. One embed per page, one word different between them.

Where the campus comes from

Planning Center's Calendar has no campus field on an event. What it has is campus tags, and Planning Center creates them for you: add your campuses under your account settings and, in Planning Center's words, "campus tags are automatically set up in Calendar." They arrive as a tag group named Campus whose tags are your campus names, and those same tags become the campus filters your congregation sees on Church Center.

PCOWidget reads that group. So the campus names you put in data-campus are the campus names already in Planning Center, spelled the same way, and a campus you add next year works the moment you tag an event with it.

Setting it up in Planning Center

1. Add your campuses in account settings. Do this first and Planning Center builds the Campus tag group in Calendar for you, so there is nothing to name or spell twice. (Planning Center: Campus tags)
2. Tag your events with a campus. An event can carry more than one campus tag, which is how a service that runs at two campuses appears on both pages. (Planning Center: Organize events with tags)
3. Consider making the Campus group required. Planning Center lets you mark a tag group required, which means an event cannot be created without one. That is what keeps a campus page from quietly going stale as staff add events and forget the tag. (Planning Center: Multi-campus setups)
4. Add data-campus to that page's embed. Build it in the Widget Display Builder if you would rather not hand-write it.

Churchwide events

Most churches leave the all-church items untagged: Christmas Eve, the annual meeting, the all-campus workday. Those belong on every campus page rather than none, which is what data-campus-untagged="1" does.

It is off by default, so a campus page is strict unless you ask otherwise. Decide by what untagged means on your own calendar. If an untagged event is usually a staff meeting or a room hold rather than something churchwide, leave it off. If you would rather be explicit, the alternative is to tag the churchwide events with every campus, which Planning Center allows and which makes them appear on each page without the attribute.

A worked example

Two campuses, Downtown and Westside. The Downtown page carries:

<!-- Downtown campus page -->
<script src="https://api.pcowidget.com/v1/calendar-widget.js?key=YOUR_KEY"
        data-layout="cards"
        data-campus="Downtown"
        data-campus-untagged="1"
        data-title="What's On at Downtown"></script>

The Westside page is the same embed with data-campus="Westside". A page that should cover both takes data-campus="Downtown,Westside", and the main church calendar page leaves the attribute off entirely and shows everything.

Responsive Breakpoints

The widget is mobile-first and adapts at these breakpoints:

REST API Reference

The widget fetches data from PCOWidget's REST endpoint. You can call this directly for custom integrations or debugging.

Endpoint

GET https://api.pcowidget.com/v1/calendar-endpoint.php

Query Parameters

Response Formats

• format=html: full HTML with wrapper div, scoped CSS, and feature flags JSON. Used for the widget's first load.
• format=fragment: layout HTML only (no wrapper, no CSS). Used by the widget for month and view changes.
• format=json: event data for custom integrations and assistants, with every time already in your church's timezone. See JSON Schema.

Example Requests

# Test your key — returns JSON event data
https://api.pcowidget.com/v1/calendar-endpoint.php?key=YOUR_KEY&format=json&limit=5

# March 2026 month grid as HTML
https://api.pcowidget.com/v1/calendar-endpoint.php?key=YOUR_KEY&format=html&layout=table&month=2026-03

# Youth events as cards
https://api.pcowidget.com/v1/calendar-endpoint.php?key=YOUR_KEY&format=html&layout=cards&tag=Youth

# Date range query
https://api.pcowidget.com/v1/calendar-endpoint.php?key=YOUR_KEY&format=json&after=2026-03-01&before=2026-06-30&limit=50

# Everything still to come in the next two months, as JSON
https://api.pcowidget.com/v1/calendar-endpoint.php?key=YOUR_KEY&format=json&months_ahead=2&hide_past=1&limit=0

JSON Schema

When using format=json, the response follows this structure. Every time is given twice: in your church's own timezone (start, start_date, start_time, weekday) and in UTC (starts_at), so nothing reading it has to convert anything. New fields may be added; existing ones keep their names.

{
  "status": "ok",
  "source": "widget",  // or "cesai" for the Events Assistant
  "timezone": "America/New_York",  // your church, from Planning Center
  "today": "2026-10-08",  // today where your church is
  "range": { "after": "2026-10-08", "before": "2026-12-08" },
  "count": 1,
  "truncated": false,  // true when a cap may have left events out
  "tag_groups": { "Ministry": ["Adult Discipleship", "Men's Ministry"] },
  "events": [
    {
      "id": "221064911",  // EventInstance ID
      "event_id": "20445373",  // Parent Event ID
      "name": "Men's Breakfast & Bible Fellowship",
      "start": "2026-10-10T07:30:00-04:00",  // your timezone, with its offset
      "end": "2026-10-10T09:00:00-04:00",
      "start_date": "2026-10-10",
      "start_time": "7:30 AM",  // null for an all-day event
      "end_time": "9:00 AM",
      "weekday": "Saturday",
      "all_day": false,
      "starts_at": "2026-10-10T11:30:00Z",  // UTC, as Planning Center sends it
      "ends_at": "2026-10-10T13:00:00Z",
      "tags": ["Adult Discipleship", "Men's Ministry"],
      "tag_groups": { "Ministry": ["Adult Discipleship", "Men's Ministry"] },
      "campus": [],  // tags from your Campus group, if you have one
      "excerpt": "This is an open group where all men are welcome...",  // plain text, up to 300 characters
      "description": "<div>...</div>",  // as written in Planning Center (HTML)
      "sermon_title": "",
      "location": "Emmanuel Lutheran Church",
      "image_url": "https://...",
      "church_center_url": "https://...",  // same as event_url
      "registration_url": "",
      "featured": false,
      "recurrence": "Weekly",
      "more_dates": 4  // only with first_only: further dates folded into this one
    }
  ],
  "meta": { ... }  // the request as the server read it, for debugging
}

Plans & BillingNew

Every church starts on the free Starter plan, with every feature and a small "Powered by PCOWidget" line under the widget. Pro removes that line, lifts the daily limit of 500 widget loads, and allows any number of websites. The current price is on the pricing section of the home page.

Upgrading to Pro

Use the Upgrade link in your welcome email, or the one on the page you saw after signing up. It opens a secure Stripe checkout for your account. Your API key and your embed code stay exactly the same: the credit disappears and the limit lifts on the next page load after payment.

Changing your card or cancelling

A self-service billing page is not available yet. Until it is, contact us and we will update your card or cancel your subscription for you. If you cancel, your widget keeps working on the Starter plan: nothing is removed from your website, and the "Powered by PCOWidget" line returns.

Already on Pro?

If an Upgrade link brought you here, your account is already on Pro and there is nothing to pay.

Troubleshooting

Widget shows nothing

1. Open your browser's Developer Tools → Console tab and look for JavaScript errors or failed network requests
2. Verify the script src URL loads directly in a browser tab. It should return JavaScript, not an error page
3. Test the endpoint directly: https://api.pcowidget.com/v1/calendar-endpoint.php?key=YOUR_KEY&format=json&limit=1
4. Confirm your API key is correct and your account is active

CORS errors in browser console

If you see "Cross-Origin Request Blocked" or CORS errors:

• Your site's domain may not be on the allowed domains list for your account
• Get support through our contact form with your domain and API key to add it
• example.com and www.example.com count as the same site, so listing either one covers both. Any other subdomain, such as events.example.com, needs its own entry
• On Wix, the Embed HTML element runs on Wix's own file domain (for example www-example-com.filesusr.com). That is recognized as your site automatically, so there is nothing extra to add
• Clear your browser cache after the domain is added

Events not showing / empty calendar

If you only just created or edited the event in Planning Center, see I changed something in Planning Center and the website hasn't caught up first. Otherwise:

• Test the JSON endpoint directly to verify your PCO credentials are working
• Confirm events exist and are published in Planning Center Calendar (not draft or hidden)
• If using data-tag, verify the tag name matches exactly how it's spelled in Planning Center (matching is case-insensitive, but spelling must be exact)
• If using data-campus, the same applies: the name has to match a tag in your Planning Center Campus tag group exactly. A campus page that comes back nearly empty is usually a campus whose events are not tagged rather than a broken filter. See Multi-Campus Churches
• Check that events are in the date range — by default the widget shows future events only

The same weekly event fills my widget

A weekly or monthly event is one event in Planning Center with many dates, and the widget shows every date in its window by default. Over a few months that can mean the same meeting five or six times, pushing one-off events like a festival or a Christmas service out of view. Add data-first-only with the tags of those repeating events (or all) and each one shows once, at its next date, with a "+N more dates" note. The Widget Display Builder has this as Repeating events: show every date?

Event times look wrong

The widget shows every event in your church's own local time. It reads that timezone straight from your Planning Center organization settings, so there is no timezone attribute on the script tag and nothing for you to set on your website.

• Open Planning Center and check the timezone recorded for your organization. If it is wrong there, it will be wrong on your site
• Correct it in Planning Center. The widget re-checks the setting periodically and picks up the change on its own, with no edit to your embed code
• If Planning Center has no usable timezone for your organization, the widget falls back to Eastern time rather than showing nothing
• Times are stored in UTC by Planning Center and converted for display, so a single event never shows two different times on two pages of your site

Past events still visible

• Make sure data-include-past is not set to "true"
• Hard refresh the page (Ctrl+Shift+R / Cmd+Shift+R) — the widget JavaScript may be cached
• If the issue persists, add a cache-busting query string to the script src: calendar-widget.js?key=YOUR_KEY&v=2

I changed something in Planning Center and the website hasn't caught up

This is expected, and it sorts itself out. Give it about a minute, then reload the page once. Changes you make in Planning Center reach your website within roughly 60 seconds.

The delay works in both directions, which covers the two most common surprises:

• Something you added isn't there yet. A new event, a corrected time, a tag you just applied
• Something you removed is still there. An event you rejected, cancelled, deleted, or unpublished from Church Center

Why it happens: your widget doesn't call Planning Center on every single page view. It reuses a recent copy of your calendar for up to a minute, which is what keeps the widget loading quickly for your visitors instead of making every one of them wait on an API call. Once that minute is up, the next page load fetches your calendar fresh.

If two widgets on your site are showing different things for a moment, that is the same delay. Each widget keeps its own copy, so they can catch up a few seconds apart. They will agree again shortly.

Still wrong after two or three minutes? Then this isn't the refresh delay, and something else is going on. Check the event's publish and approval state in Planning Center, confirm any data-tag or data-campus spelling matches the tag exactly, and make sure the event falls inside the date range your widget is showing. See Events not showing / empty calendar above, or get support through our contact form and we will take a look.

Sermon title not showing on simple tiles

• Confirm the line is in the Details field of the event in Planning Center Calendar (not the title or notes on a separate app)
• The line must begin with sermon: (with a colon) — no space before the colon
• The line can appear anywhere in the Details field, but must be on its own line
• Sermon titles only display on the simple layout