WordPress Plugin

Overview

The PinBuilds WordPress Plugin is a "set-and-forget" integration that automatically generates and schedules Pinterest pins for every post you publish. Once configured, all AI generation, scheduling, and Pinterest publishing happens automatically — no manual intervention needed.

Installation

1. Download the plugin from Settings > API Keys in PinBuilds (or from the WordPress Plugin Directory).
2. In WordPress, go to Plugins > Add New > Upload Plugin and install the ZIP file.
3. Activate the plugin.
4. Go to Settings > PinBuilds in your WordPress admin.

Setup

1. Connect Your API Key

1. In PinBuilds, go to Settings and create an API key.
2. Copy the key (it starts with pb_live_).
3. In WordPress, go to Settings > PinBuilds and paste your API key.
4. Click Connect — the plugin will verify the key and show your subscription status.

Your API key is encrypted at rest in WordPress using AES-256-CBC.

2. Configure Your Profile on PinBuilds

All generation and scheduling settings are managed on the PinBuilds dashboard Settings page, not in WordPress:

• Profile type: Use a Website / Blog profile that matches your WordPress domain. Shopify and Etsy profiles are for product-store workflows, not WordPress posts.
• Generation settings: Generation mode (Image, Infographic, or Mix), text overlay (On/Off), pins per post, image styles
• Scheduling settings: Pins per day, posting time window
• Pinterest connection: Connect your Pinterest account and select boards

The WordPress plugin reads these settings automatically from your PinBuilds profile.

3. Setup Checklist

The plugin's Settings page includes a setup checklist to guide you:

1. API key connected
2. Site profile created on PinBuilds (matching your WordPress domain)
3. Pinterest account connected
4. Boards selected
5. Ready to go

How It Works

Automatic Pin Generation

Once connected, the plugin works automatically:

1. You publish a post — WordPress fires the publish hook.
2. The plugin sends the post URL to the PinBuilds API.
3. PinBuilds generates pins — AI text + images based on your profile settings.
4. Pins are auto-scheduled to your connected Pinterest boards.

That's it. No buttons to click, no manual steps.

What Gets Sent

The plugin sends only the post URL to PinBuilds. The server fetches the article content, extracts a title from the URL, and generates everything server-side. This ensures pins generated via WordPress are identical in quality to dashboard-generated pins.

Generic Page Filtering

The plugin automatically skips non-article pages: about, contact, privacy, terms, category archives, pagination, search, cart, checkout, and login pages. Only real article/post URLs are processed.

Backlog Processing

For existing posts that were published before you installed the plugin:

1. Go to Settings > PinBuilds in WordPress.
2. Under Backlog Processing, set how many posts to process per day (1-10, default: 3).
3. Click Start Backlog — the plugin will process your existing posts daily via WordPress cron.

How It Works

• The plugin queries PinBuilds to determine which posts haven't been processed yet (server is the source of truth).
• Each day, it processes N posts (your configured limit), generating and scheduling pins for each.
• Processing pauses automatically when your monthly generation limit is exhausted.
• Once all posts are processed, the backlog stops.

Duplicate Prevention

The plugin uses multiple layers to prevent duplicate pin generation:

• Server-side article tracking: PinBuilds permanently tracks every processed URL.
• 24-hour cooldown: A post won't be re-processed within 24 hours of its last generation.
• Optimistic locking: When generation starts, the post is immediately marked to prevent the publish hook and backlog cron from processing it simultaneously.

Troubleshooting

Pins not generating for new posts

1. Verify your API key is connected (Settings > PinBuilds).
2. Check that a Website / Blog profile exists on PinBuilds matching your WordPress domain.
3. Ensure the post is a real article URL (generic pages are skipped).

Backlog not progressing

1. Check if your monthly generation limit is exhausted (shown on the Dashboard).
2. Verify WordPress cron is running (some hosts disable wp-cron.php).
3. Try clicking "Start Backlog" again to re-trigger the cron.

"API key invalid" error

1. Verify the key in PinBuilds Settings > API Keys (keys can be revoked).
2. Re-enter the key in WordPress Settings > PinBuilds.

Generation takes too long

Pin generation typically takes 60-120 seconds per post (AI text + image generation + scheduling). The plugin uses a 180-second timeout for the generate endpoint. If you're seeing timeouts, your hosting provider may have a low execution time limit.