Circle Setup Guide
With Circle connected, each subscriber is added to the Circle spaces you choose for their tier, matched by their email address. Circle sends its own invitation, so subscribers have nothing to set up on your site. This guide connects one show. Each show connects its own Circle community, so repeat it for every show that has one.
Before you start, switch Community Integrations on for the show under Benecaster → Settings → Add-ons → the Community Integrations card → Active on. The Community Integrations Overview explains how members are kept in step.
What You Need
- A Circle plan that includes Admin API access. Benecaster manages members through Circle’s Admin API. On a plan without it, every test and every sync fails with Your Circle plan does not include Admin API access, which Benecaster needs to manage members. Upgrade the plan in Circle, then test again.
- An Admin API key, created in your Circle community’s Developers settings.
- Your community’s address, such as
https://community.example.com. - Spaces, and member tags if you want them, already made in Circle. Benecaster adds people to spaces and tags; it doesn’t create them.
Connecting Circle
- Go to Benecaster → Shows, click Settings on the show’s card, and choose Community.
- In the Circle panel, paste your key into Circle API key. The key is stored encrypted and never shown again; once saved, the box reads A key is saved. Enter a new one to replace it.
- Type your community’s address into Community URL. Benecaster adds
https://if you leave it off. - Click Save. Saving a new key tests it straight away.
- If you didn’t change the key, click Test connection. It’s available once a key is saved.
When the test passes, the panel reads Connected to {your community’s name}. and lists your spaces and member tags. A saved key that hasn’t been tested reads A key is saved but the connection has not been tested.
Remove key deletes the saved key. Until you save another, nothing is sent to Circle for this show.
Choosing Spaces and Tags for Each Tier
Once the test passes, the panel lists each of the show’s tiers:
- Spaces for each tier: tick the spaces each tier joins. A member joins every space ticked for their tier, and leaves those spaces when their tier no longer has them.
- Member tags for each tier (optional): tick the Circle member tags each tier gets, for filtering members and sending targeted broadcasts in Circle. This appears only when your community has member tags.
A space or tag can be ticked for several tiers. If the show has no tiers yet, the panel says This show has no tiers yet. Add them under Memberships → Tiers, then come back to map them.
Click Save when you’re done. Saving a changed choice updates every member already on Circle in the background: they join the newly ticked spaces and tags and leave the ones you unticked.
When Someone Leaves
A member who leaves every tier above loses the spaces and tags their tier gave them, and stays in your community.
Tick Remove from the community entirely on cancel to also take them out of the community itself. It’s off until you tick it. Circle calls this deactivating a member: their account stays in Circle, and Circle restores it if they subscribe again and are added back.
Switching Community Integrations off for the show never removes anyone.
What Happens on Circle
- Subscribing. The subscriber is invited to your community, or added back if they were in it before, with their tier’s spaces and tags. Circle sends its invitation the way your community is set up to.
- Changing tier. Only the spaces and tags that differ change.
- Leaving. As above.
- Changing email address. Circle can’t change a member’s email. When a subscriber changes theirs on your site, the new address is added to their spaces and tags, which invites that address to the community, and the old address is taken out of them. Their posts and history stay with the old Circle account.
- Only what Benecaster added is taken away. A space you gave someone in Circle by hand stays.
A subscriber with no email address on your site can’t be matched, and shows under Member sync with This member has no email address on this site, so Circle cannot match them.
What Subscribers See
On the account page, the show’s card ends with a Community section reading Your membership includes this show’s community on Circle. and an Access your community link, which opens your community in a new tab. It appears only when the subscriber’s tier is mapped to at least one space, so nobody is shown a link to a community their tier doesn’t open.
Add {{circle_community_url}} to any of this show’s Benecaster emails, such as the welcome email, to include the same address. It’s listed under Merge tags on the Community tab with Copy.
The Setup Wizard Step
Benecaster’s setup wizard includes Connect your Circle community. It has the same Circle API key and Community URL boxes and a Test connection button, which saves both for the show and tests them. Continue is held until a test passes, which shows Connected to {name}. Choose which spaces each tier joins on this show’s Community settings. Choose I’ll set this up in Settings. to skip it.
The step doesn’t choose spaces: do that on the show’s Community tab afterwards. If you install the add-on after finishing setup, each show it’s switched on for that has no Circle connection is offered the step once. Connecting Circle on the show’s Community tab takes the step back.
Troubleshooting
Test connection and Member sync show Circle’s answer in words:
| Message | What to do |
|---|---|
| Circle did not accept this API key. Check it was copied in full from your community’s Developers settings. | Copy the key again, paste it into Circle API key, and click Save. |
| Circle refused this API key. Use an Admin API key from your community’s Developers settings. | The key isn’t an Admin API key. Create one in the Developers settings. |
| Your Circle plan does not include Admin API access, which Benecaster needs to manage members. Upgrade the plan in Circle, then test again. | Upgrade your Circle plan, then click Test connection. |
| Circle could not find what was asked for. A space or tag may have been deleted in Circle. | Click Test connection, check the space and tag choices, and click Save. |
| WordPress could not reach Circle. Check that this site can make outgoing connections, then try again. | Your host may be blocking outgoing connections. Ask them. |
| Circle asked us to slow down. Wait a minute, then test again. | Wait a minute. During a sync, the member is retried shortly by itself. |
| Circle answered with an error (HTTP {code}). Try again in a few minutes. | A problem on Circle’s side. Members are retried by themselves. |
| Save your Circle API key first, then test the connection. | Save a key before testing. |
| Enter your Circle community’s address, for example https://community.example.com. | Community URL isn’t a web address. Correct it and save. |
| The API key could not be saved. Check that this show has been saved at least once, then try again. | Save the show’s settings once, then save the key again. |
A member who keeps failing shows as Failed under Member sync after the last retry. Fix the cause, then click Resync now.
Privacy and Removing the Add-on
Circle receives each subscriber’s email address, display name and tier. Your site keeps the address it used on Circle and the spaces and tags it added, so it can still remove the person after their address changes or their account is deleted. An erasure takes the person out of those spaces and tags, and out of the community when Remove from the community entirely on cancel is ticked. Their Circle account itself is never deleted: delete it in Circle if the request covers it. See Privacy and Data Handling.
Deleting the add-on from Plugins deletes the saved Circle API key and removes nobody from Circle.
See Also
Need this built rather than just documented? See our services →
Last updated