All documentation.
In one place.

Version 3.0.3 | For shelter administrators and website managers

1. What is ShelterSync?
2. Requirements
3. Installation and First Setup
4. The ShelterSync Admin Menu
• Dashboard
• Settings
• Animal Display
• Filters & Sort
• Custom Fields (PLUS)
• Online Forms
• Notifications
• Diagnostic Log
• Help

1. Displaying Animals on Your Site
• Adoptable Animals
• Adopted Animals
• Lost, Found & Stray Animals
• Online Forms

1. How the Listing Works
2. PLUS Features Overview
3. Troubleshooting

1. What is ShelterSync?

ShelterSync connects your WordPress website directly to your ShelterManager account. It automatically pulls your animal records from ShelterManager, caches them on your server, and displays them on your site in responsive grids with full animal detail overlays.

Your site visitors can search, filter, and sort animals, open a detailed profile for any individual animal, and click through to your adoption application or enquiry form.

ShelterSync comes in two tiers:

• Core — free, published on WordPress.org. Includes the full adoptable animals listing, adopted animals display, lost/found/stray listings, online forms, search, pagination, attribute icons (including vaccination status), bonded animal labelling, reserved animal badge, video embedding, and more.
• PLUS — a paid upgrade, activated with a licence key from sheltersync.app. Adds photo galleries, additional filters, filter display order configuration, custom sync intervals, merged bonded profiles, custom fields, drag-and-drop display order configuration, reserved CTA suppression, CSS styling controls, and more.

Throughout this guide, features marked PLUS require an active PLUS licence.

2. Requirements

• WordPress 6.0 or later
• PHP 8.0 or later (PHP 8.1+ recommended)
• An active ShelterManager account with API access, or a self-hosted ASM3 instance
• HTTPS on your website (strongly recommended; required for cloud ShelterManager connections)

3. Installation and First Setup

Installing the plugin

1. In your WordPress admin, go to Plugins → Add New Plugin.
2. Search for ShelterSync for ShelterManager.
3. Click Install Now, then Activate.

Alternatively, download the zip from WordPress.org and upload it via Plugins → Add New Plugin → Upload Plugin.

Entering your ShelterManager credentials

After activation, the ShelterSync menu appears in your WordPress admin sidebar.

1. Go to ShelterSync → Settings.
2. Under the General tab, enter your Account ID, Username, and Password.
3. Click Save Settings.
4. Click Test Connection to confirm the plugin can reach ShelterManager.

Your credentials are encrypted before being stored. They are never written to log files or exposed in page source.

Activating your PLUS licence

If you have purchased a PLUS licence from sheltersync.app:

1. Go to ShelterSync → Settings → Licence.
2. Enter your licence key and click Activate.
3. The key is validated against the ShelterSync licence server. PLUS features are unlocked immediately on success.

The licence is re-validated daily in the background. A 7-day grace period keeps PLUS features active if the licence server is temporarily unreachable. If your licence expires or is deactivated, the plugin reverts to Core behaviour and a notice appears on ShelterSync admin pages.

Running your first sync

After saving valid credentials, a background sync is scheduled automatically. To trigger one immediately, go to ShelterSync → Dashboard and click Sync Now.

Adding the listing to a page

Add [shelter_adoptables] to any WordPress page or post. Your adoptable animals will appear once a sync has completed.

4. The ShelterSync Admin Menu

All ShelterSync settings live under the ShelterSync top-level menu in your WordPress admin sidebar.

Dashboard

Your at-a-glance status view showing connection status, last sync timestamp, the Sync Now button, and any admin notices (sync failures, licence warnings, credential errors).

A dismissible notice appears here after plugin activation or update confirming that a background sync has been scheduled.

Settings

General tab

• Account ID, Username, Password — your ShelterManager login credentials (cloud mode)
• Test Connection — verifies credentials and connectivity. In self-hosted mode, the test targets your configured service URL.
• Sync Interval — Core: fixed 1-hour schedule. PLUS configurable from 15 minutes to 24 hours.
• Cache TTL — PLUS how long cached data is considered fresh before a re-sync is attempted.
• Placeholder Image — fallback image when an animal has no photo. Upload a square image for best results.
• No Results Message — shown when visitor filters match no animals.
• Unavailable Message — shown when the cache is empty and the API cannot be reached.
• Weight Unit — unit label for weight fields: kg, lbs, or None.
• Pagination — enable or disable paginated display globally.
• Animals per page — default page size (5, 10, 15, 20, or 25).

Licence tab

• Licence Key — enter your ShelterSync PLUS key here and click Activate. The key is masked on display after activation (last four characters only).
• Status — shows whether the licence is active, expired, inactive, or in the grace period.
• Activation date / Expiry date — displayed when active.
• Deactivate — frees your activation slot on the licence server and reverts PLUS features immediately.

To purchase or manage a licence, visit sheltersync.app.

Advanced tab

• API Mode — choose Cloud (default, for sheltermanager.com accounts) or Self-Hosted (for ASM3 instances you host yourself).
• Service URL (Self-Hosted mode only) — the base URL for your ASM3 service endpoint. The Account ID field is hidden in self-hosted mode. HTTP is permitted but a warning is shown on all ShelterSync admin pages when a non-HTTPS URL is configured.
• WP-Cron guidance — for high-traffic sites, configuring an external cron job is recommended for reliable background syncing.

Animal Display

Controls what information appears on animal cards and in detail overlays. The page has three tabs: Adoptable Animals, Adopted Animals, and Lost, Found & Stray. Each tab has its own independent configuration.

Adoptable Animals tab

Field display — toggle individual fields on or off for the animal card and detail overlay.

Description field — choose whether the animal description comes from Animal Comments or Website Media Notes in ShelterManager.

Call to Action — configure the button shown in animal detail overlays:

• External URL or WordPress page destination
• Button label (default: Apply to Adopt)
• Open in new tab toggle
• PLUS Reserved CTA suppression — when enabled, the CTA button is replaced by a notice banner for animals with an active reservation. Default banner text: Reserved — Not Available For Adoption. The banner text is configurable. Styled using the reserved badge colour (--sheltermgr-reserved-badge-bg). This applies to adoptable overlays only.

Field labels PLUS — override the displayed label for any field. The reserved key customises the label on the reserved badge.

Display order (overlay) PLUS — drag-and-drop field ordering for detail overlays. Add section dividers to group fields visually.

Display order (card) PLUS — separately configure card field order.

Icon configuration — controls attribute icons (Neutered/Spayed, Microchipped, House Trained, Vaccination, and others):

• Toggle each icon on or off
• PLUS Customise positive, negative, and unknown state labels
• PLUS Upload a replacement icon via the WordPress Media Library

Bonded badge — configure the badge shown on bonded animal list cards: icon (Dashicons), label text (max 20 characters, default: BONDED), and visibility toggle.

CSS Configuration PLUS — see Section 7.

Adopted Animals tab

Independent configuration for the [shelter_adopted] shortcode:

• Field display, description field selector, icon configuration, display order (overlay and card, PLUS)
• No Call to Action is configured here — adopted animal overlays are success story profiles, not adoption enquiry pages
• Vaccination icon is available for adopted animals

Lost, Found & Stray tab

Independent configuration per sub-type (Lost, Found, Stray):

• Field display, icon configuration, and CTA per sub-type
• Shared display order with optional per-sub-type override PLUS
• Vaccination icon is available for Stray animals; absent for Lost and Found (those field sets do not include vaccination data)

Filters & Sort

Controls which filter dimensions and sort options are available to visitors, per listing area.

Adoptable Animals tab

Filter visibility — toggle each filter dimension:

The Reserved Status filter lets visitors show only unreserved animals (the most common use case), or only reserved animals. Values shown to visitors are Yes and No.

Sort configuration — toggle which sort options are available.

Filter display order PLUS — drag-and-drop reordering of filter dimensions within the filter overlay. A Reset to Default button restores the factory order. Custom field filter dimensions are appended automatically when added — they are never silently dropped.

Adopted Animals tab

Filter visibility and sort configuration for the adopted animals context. Adoption Date is available as a sort option here.

Lost, Found & Stray tab

Filter visibility including date range filters. Date Reported is available in Core; Date Lost and Date Found are available with PLUS.

Custom Fields PLUS

Add any ShelterManager API field to cards, overlays, filters, and sorting:

1. Click Discover Fields to load available API field keys from your cached data.
2. Click Add Field and configure: API field key, display label, listing types (Adoptable, Adopted, Lost, Found, Stray), card/overlay visibility, filterable, sortable.
3. Click Save Custom Fields.

Custom fields appear in display order panels for their configured listing types. Up to 20 custom fields can be configured.

Online Forms

Configure ShelterManager online forms for use with the [shelter_form] shortcode.

1. Click Add Form and enter the ShelterManager form ID and a Display Label.
2. Use [shelter_form form="Your Display Label"] on any page.

Supported field types: Text, Notes, Lookup (select), Yes/No, Checkbox, Date, Signature, Adoptable Animal selector, Section Headings.

IMAGE fields display a note directing applicants to email photos separately — a ShelterManager API restriction prevents remote file uploads.

Notifications

Email notifications to a configurable address for sync failures, sync resolution, credential errors, and credential resolution. Each notification type is independently togglable. Repeated failure notifications are suppressed for 24 hours after the first alert.

Diagnostic Log

Timestamped log of plugin events: syncs, failures, API errors, auto-sync triggers, licence validation events. Maximum 50 entries (configurable). Use this when troubleshooting API or sync issues.

Help

Links to ShelterSync documentation, support, and external cron configuration guidance.

5. Displaying Animals on Your Site

Adoptable Animals

Basic usage:

[shelter_adoptables]

Pre-filtering — include parameters:

[shelter_adoptables species="Rabbit"]
[shelter_adoptables species="Rabbit+Cat" sex="Female"]
[shelter_adoptables reserved="no"]
[shelter_adoptables species="Cat" exclude_reserved="yes"]

Pre-set filter values lock the corresponding filter control — visitors cannot change them. To allow visitor adjustment, use allow_override="true" (PLUS).

Exclusion parameters:

Exclusion parameters remove animals from the dataset server-side before the page renders. Excluded animals are entirely absent from page source.

[shelter_adoptables exclude_species="Rabbit"]
[shelter_adoptables exclude_reserved="yes"]
[shelter_adoptables species="Cat" exclude_sex="Male"]

Exclusions can be combined with include parameters on the same shortcode.

Available filter parameters:

Exclusion parameters — prefix any filter parameter with exclude_:

Other parameters:

Adopted Animals

[shelter_adopted]
[shelter_adopted species="Rabbit"]
[shelter_adopted per_page="10"]

Displays recently adopted animals. The date range is configured under ShelterSync → Settings. Configure display options independently under ShelterSync → Animal Display → Adopted Animals tab.

The same filter and exclusion parameters available for [shelter_adoptables] work here (excluding PLUS-only extended dimensions not applicable to the adopted context).

Lost, Found & Stray Animals

[shelter_community]
[shelter_community type="lost+found"]
[shelter_lost species="Cat"]
[shelter_community exclude_species="Dog"]

The type parameter on [shelter_community] narrows which sub-types are shown. All filter and exclusion parameters apply.

Online Forms

[shelter_form form="Adoption Enquiry"]

The form parameter must match the Display Label configured under ShelterSync → Online Forms exactly (case-sensitive).

6. How the Listing Works

Reserved badge

Animals with an active reservation in ShelterManager automatically show a Reserved badge — a small label overlaying the top-right corner of the animal's photo on list cards, and the top-right of the photo column in the detail overlay. No admin configuration is needed for the badge to appear.

The badge label defaults to "Reserved" and can be customised via ShelterSync → Animal Display → Field Labels (field key: reserved). The badge colour defaults to green and can be changed by adding --sheltermgr-reserved-badge-bg to your theme CSS. To remove the badge entirely, add .sheltermgr-reserved-badge { display: none; } to your theme.

Vaccination icon

The vaccination icon in animal overlays shows the animal's vaccination status, calculated from ShelterManager's vaccination count data:

• Tick (positive) — at least one vaccination given and no outstanding vaccinations
• Cross (negative) — outstanding vaccinations remaining
• Question mark (unknown) — vaccination data absent from the record

Search, filters, sorting, and pagination

• Search — real-time, matches name, breed, species, colour, and description
• Filters — slide-out panel via the Filters button; active filter count shown as a badge; Clear Filters link on the listing when active
• Sorting — sort field and direction controls above the grid
• Pagination — page controls below the grid; visitors can adjust per-page count

Animal detail overlay

Clicking any animal card opens the full detail overlay. Features include photos (gallery for PLUS), attribute icons, all configured fields, video embedding, a CTA button, and bonded partner navigation. Direct URL linking works — sharing a URL containing ?animal=123 opens that animal's overlay automatically. Keyboard navigable; press Escape to close.

7. PLUS Features Overview

Activate PLUS under ShelterSync → Settings → Licence with a key from sheltersync.app.

CSS Configuration lives under ShelterSync → Animal Display → Adoptable Animals → CSS Configuration. A live preview updates as you adjust values. Available controls: primary colour, secondary colour, text colour, heading colour, border colour, badge colours (positive/negative/unknown/reserved), body and heading font stacks, card border radius (0–24px), card shadow, card column count (1–5). Values output as CSS custom properties on .sheltermgr-container without modifying plugin files.

8. Troubleshooting

PLUS features are not available after updating

PLUS licensing now requires validation against the sheltersync.app licence server. Go to ShelterSync → Settings → Licence, enter your key, and click Activate. If you are within the 7-day grace period, PLUS remains active while you complete this.

Attribute icons are showing the wrong state (cross instead of tick)

Update to v3.0.2 or later. Earlier versions had a bug where ShelterManager's integer attribute fields (which can return 0) were taking priority over the string NAME fields (which return "Yes"), causing the icon to show as negative when it should have been positive. v3.0.2 fixes the lookup priority for all 11 attributes.

Animals are not showing on the page

1. Check ShelterSync → Dashboard for connection status and last sync timestamp.
2. Check credentials under Settings and click Test Connection.
3. Click Sync Now to force a fresh sync.
4. Confirm the shortcode is placed correctly on a published page.

Reserved animals are still receiving adoption enquiries

Enable the Reserved CTA suppression toggle under ShelterSync → Animal Display → Adoptable Animals → Call to Action (PLUS). This replaces the CTA button with a notice banner for reserved animals. Alternatively, use exclude_reserved="yes" on the shortcode to remove reserved animals from the listing entirely.

Self-hosted connection is failing

Check that the Service URL under ShelterSync → Settings → Advanced is correct and includes the full path to the service endpoint (e.g. http://yourserver.example.com/service). Trailing slashes are stripped on save. Run Test Connection to verify — the success message will confirm the endpoint URL being used.

The vaccination custom icon I uploaded is not appearing

Update to v3.0.3. Earlier v3.0.x releases had a bug where the vaccination icon key was missing from the custom icon save handler, so uploads were silently discarded. After updating, re-upload the icon under ShelterSync → Animal Display → Icons → Custom Icons.

The listing shows "listings temporarily unavailable"

The cache is empty and the plugin cannot reach ShelterManager. Check the Diagnostic Log for details. The message resolves automatically once connectivity is restored and a sync completes.

Filters are not appearing

Check ShelterSync → Filters & Sort and confirm filter dimensions are toggled on. Also check that shortcode filter parameters are not locking those dimensions.

Sync is running but data is stale

Your hosting platform may not be running WP-Cron reliably. Follow the guidance under ShelterSync → Help to configure an external cron job.

ShelterSync for ShelterManager is developed by Reput8n. Licensing and support: sheltersync.app