CityPost Classifieds – Documentation

CityPost Classifieds – Documentation

Version 1.0.5 (CityPost Core 1.0.3) · GPLv2 or later · Text domains citypost (theme) and citypost-core (plugin)

1. Installation

  1. Go to Appearance → Themes → Add New → Upload Theme, upload citypost-1.0.5.zip and switch the theme on.
  2. A notice appears at the top of the dashboard: click Install CityPost Core. The companion plugin is bundled with the theme at citypost/plugins/citypost-core.zip inside the theme package (you can also upload that zip or citypost-core-1.0.3.zip from Plugins → Add New → Upload Plugin). When the plugin turns on it creates the user pages (Login, Sign Up, Dashboard, Add Listing, My Listings, Favorites), the Pricing page and the default category tree.
  3. Go to Settings → Permalinks and click Save once so the listing URLs work.

Upgrading from an older version? See Upgrading.

2. Setup

  • CityPost → Settings: currency, contact details, listings per page, colours, monetization (membership plans) and maps.
  • CityPost → Sample Data: installs or removes 40 sample ads across 10 US cities with featured images.
  • Site title and logo: Appearance → Customize → Site Identity.
  • Google Maps is optional; it is only loaded when you add your own Maps API key in Settings.

3. Categories

Manage categories under Listings → Categories. Categories are hierarchical: top-level categories show on the homepage grid with an icon, and their sub-categories are listed below. Add, rename or remove any of them. Default tree:

Category Sub-categories
🛍️ Buy & Sell Antiques & Collectibles, Arts & Crafts, Baby Items, Books, Musical Instruments, Tools, Free Stuff, Other
🚗 Vehicles Cars & Trucks, Motorcycles, RVs & Campers, Boats & Watercraft, ATVs & Snowmobiles, Auto Parts & Tires
🏠 Real Estate Houses for Sale, Condos for Sale, Apartments for Rent, Rooms & Roommates, Commercial & Office, Land for Sale, Vacation Rentals
💼 Jobs Full-Time, Part-Time, Remote & Work From Home, Trades & Construction, Hospitality & Restaurants, Office & Admin, Healthcare
🛠️ Services Cleaning, Moving & Storage, Renovations & Repairs, Lessons & Tutoring, Health & Beauty, Computer & IT, Childcare
🐾 Pets Dogs & Puppies, Cats & Kittens, Birds, Fish & Aquariums, Pet Supplies, Lost & Found Pets
💻 Electronics Computers & Laptops, TVs, Smart Phones, Accessories, Cameras, Audio, Video Games & Consoles
🛋️ Furniture Couches & Sofas, Beds & Mattresses, Tables & Chairs, Dressers & Wardrobes, Desks & Office Furniture, Outdoor Furniture
🌿 Home & Garden Appliances, Kitchen & Dining, Home Décor, Lighting, Garden & Patio, Tools & Workshop, Heating & Cooling
👗 Fashion Women’s Clothing, Men’s Clothing, Kids’ Clothing, Shoes, Bags & Accessories, Jewellery & Watches
⚽ Sports & Hobbies Bikes, Exercise & Fitness, Camping & Hiking, Golf, Winter Sports, Water Sports, Toys & Games
🤝 Community Events, Classes & Workshops, Volunteers, Lost & Found, Rideshare, Garage Sales

Locations are managed under Listings → Locations.

4. Listings (ads)

  • Admins add ads under Listings → Add New: title, description, featured image, gallery, price, condition, address, seller phone/email, category and location.
  • Members post ads from the front end via Post Ad (Add Listing page) and manage them in their Dashboard.
  • Tick Featured to show an ad in the homepage “Featured Ads” row and with a Featured badge.
  • Listings archive: /listings/; single ad: /listing/ad-name/; category: /ads/category-name/.

5. Homepage

The homepage (front-page.php) is built automatically: a large search bar (keyword, category, location), the category grid with icons and sub-categories, Featured Ads, Recent Ads and a “Post Ad” call to action and a Craigslist-style “Choose a city” list. Cities are the Locations taxonomy (Listings → Locations); each city has its own page at /location/<city>/. Searches and the ads archive (/listings/) filter by keyword, category, city, condition and price, and sort by newest or price. It works with Settings → Reading set to either “Your latest posts” or a static page.

All pages are full width and responsive. The sticky header contains the logo, the Primary menu, a quick search box, a Sign In / Register link (shows Dashboard when logged in) and the Post Ad button. Assign menus in Appearance → Menus (Primary and Footer locations). Footer widget columns are under Appearance → Widgets.

7. Plans & Stripe payments

Membership plans

Manage plans under CityPost → Membership Plans (price, duration, ad limit and how many Featured / Highlighted / Urgent boosts are included). Defaults: Free (3 ads), Basic $29.99 / 30 days (25 ads, 3 featured, 5 highlighted, 2 urgent) and Business $79.99 / 30 days (unlimited ads, 10 / 20 / 10). Turn plans on in Settings → Monetization → Enable Membership Plans. Members choose a plan in Dashboard → My Membership or on the Pricing page (any page containing [citypost_pricing_table]). Free plans start straight away; paid plans open Stripe Checkout and start as soon as the payment is confirmed.

Members admin (plans & bonus credits)

Under CityPost → Members, click Manage on a seller to:

  • Assign a membership plan (Free / Basic / Business or any plan you created). Choose expiry as the plan’s default duration from today, a custom date, or never expires. This uses the same membership records as Stripe checkout, so listing and boost limits apply immediately.
  • Cancel membership to remove the active plan.
  • Set bonus credits: Featured, Highlighted, Urgent and Extra listings. Extra listings raise the seller’s ad limit on top of their plan. Featured / Highlighted / Urgent credits let the seller apply that boost free from My Listings (same duration as the paid boost setting) and are used after plan allowance slots, before paid checkout.
  • Change WordPress role separately (subscriber / contributor / author) if needed.

Remaining credits appear in the Members table and on the seller’s Dashboard (home panel and My Membership page), including the raised listing limit. My Listings boost buttons show (Free) when a plan slot or bonus credit is available. Admin grants and plan assignments are logged under CityPost → Payments as amount 0 with status admin_grant.

Paid ad boosts

In Dashboard → My Listings each published ad shows + Featured, + Highlighted and + Urgent buttons. If the seller’s plan still has free boost slots, the boost is applied immediately at no charge. If not, a bonus credit (if the admin granted one) is used next. Otherwise the seller pays through Stripe Checkout. Prices and durations are set in Settings → Monetization (defaults: Featured $9.99 / 7 days, Highlighted $4.99 / 7 days, Urgent $2.99 / 7 days). Buying again while a boost is running extends it. Boost buttons only appear on published ads; on the Add Listing form, boosts you cannot get free are shown greyed out with the note “Needs payment”.

The three boosts

  • Featured: the ad is listed first in search results and the listings archive, appears in the homepage “Featured Ads” row and shows a Featured badge.
  • Highlighted: the ad shows a purple “Highlighted” badge on its card and ad page.
  • Urgent: the ad shows a red “Urgent” badge on its card and ad page, for sellers who need a quick sale. It does not change the sort order.

Each boost lasts for the number of days set in Settings → Monetization and switches off by itself when it ends. Turn all boosts on or off with Enable Listing Boosts.

Connecting Stripe

  1. Create a free account at stripe.com. Leave the dashboard in Test mode.
  2. Go to Developers → API keys and copy the Publishable key (pk_test_…) and Secret key (sk_test_…).
  3. In WordPress open CityPost → Settings → Payments, set Stripe Mode to Test, paste both test keys, choose your currency and click Save Changes. Saved secret keys are shown masked; leave a field blank to keep the saved value.
  4. Webhook (recommended): copy the webhook URL shown at the top of the Payments tab (it looks like https://your-site.com/wp-json/citypost/v1/stripe-webhook). In Stripe go to Developers → Webhooks → Add endpoint, paste the URL and select the event checkout.session.completed. Save, then reveal the endpoint’s Signing secret (whsec_…) and paste it into Webhook Secret.
  5. Test: log in as a member, choose the Basic plan and pay with card 4242 4242 4242 4242, any future expiry date, any CVC and any postcode. You return to My Membership with the plan active. Each payment appears under CityPost → Payments.

Payments are confirmed twice for reliability: by the webhook, and again when the buyer returns from Stripe. Each Checkout session is only ever applied once. Until a secret key is saved, pay buttons show a friendly “payments are not configured” message and free plans still work.

Going live

  1. Finish setting up your Stripe account (business and bank details).
  2. Switch the Stripe dashboard to live mode and copy the live keys (pk_live_…, sk_live_…).
  3. Add the same webhook URL again in live mode with checkout.session.completed, and copy its new signing secret.
  4. In Settings → Payments paste the live keys and the live webhook secret, set Stripe Mode to Live and save. Your site must use HTTPS.

Upgrading

  1. Back up your database and wp-content folder first (most hosts have a one-click backup).
  2. Go to Appearance → Themes → Add New → Upload Theme, upload citypost-1.0.5.zip and choose Replace current with uploaded.
  3. Go to Plugins → Add New → Upload Plugin, upload citypost-core-1.0.3.zip (also inside the theme at citypost/plugins/citypost-core.zip) and choose Replace current with uploaded. Keep the plugin turned on.
  4. Go to Settings → Permalinks and click Save once.
  5. Check CityPost → Settings → Monetization. Enable Listing Boosts is off on new installs; if you sell boosts, make sure it is ticked.

All ads, members, messages, plans, payments, credits and favourites are kept. Coming from 1.0.1 (theme only, no plugin): upload the new theme, then click Install CityPost Core in the dashboard notice; a one-time upgrade step moves everything across automatically.

What changed in 1.0.5: if CityPost Core is turned off, your homepage now shows your normal WordPress front page (latest posts, or the static page set in Settings → Reading) instead of a notice. Only administrators see a small reminder bar to install Core. The theme and plugin now ship the same documentation.

What changed in 1.0.4 that site owners may notice:

  • Password reset links now open a “choose a new password” form on your Forgot Password page. Links in emails sent before the upgrade still work until they expire (24 hours).
  • Guest favourites and compare lists saved by older versions are read and converted automatically. When a guest logs in, their saved favourites move to their account.
  • Ad limits are checked every time an ad goes live or is sent for review, not only when it is first created.

Member rules: boosts, ad limits and suspension

When a boost is applied

A Featured, Highlighted or Urgent boost is applied in exactly three cases, checked in this order:

  1. the member’s active plan still has an unused slot for that boost (only when membership plans are on);
  2. the member has a bonus credit for it (the credit is used up);
  3. Stripe confirms a payment for it.

Anything else, such as ticking a box on the ad form without a slot or credit, is refused and the ad is saved without the boost. Every free boost is logged under CityPost → Payments with amount 0.

Turning boosts off

Untick Enable Listing Boosts to stop selling boosts. The boost buttons and the form’s Promote section disappear, and the server refuses any new boost request, including free slots and credits (credits are kept for later). Boosts already running stay on their ads until they end. A checkout a buyer has already paid for is still delivered, because the money was taken.

Ad limits

Each plan’s ad limit counts ads that are live or waiting for review. Drafts don’t count, so members can prepare as many as they like. The limit is checked each time an ad is published or sent for review, including publishing an older draft, and two requests at the same moment cannot both slip past it. When a plan expires, the member can still save drafts but cannot publish until they choose a plan again.

Suspended members

Suspend a member from CityPost → Members → Suspend. They are logged out of every device straight away and their live ads are moved back to drafts.

  • They can: log in, see their dashboard, edit their profile and password, delete their own ads, use favourites and read or send enquiries.
  • They cannot: add, edit or publish ads, buy or apply boosts, or change plan.

Click Unsuspend to restore full access. Their ads stay as drafts until they publish them again.

Troubleshooting

Login, Dashboard or other account pages are missing (404 or blank)

  1. Make sure CityPost Core is installed and turned on under Plugins. Without it the theme works as a normal blog theme.
  2. If an account page was deleted or trashed, just load any page of your site: CityPost Core notices and restores it (trashed pages are restored, deleted ones are recreated). Pages you already have are left alone.
  3. Save Settings → Permalinks once.

Ads or categories show “Page not found”

Go to Settings → Permalinks and click Save. Any setting other than “Plain” works. On Nginx, ask your host to enable WordPress pretty permalinks. Don’t create a normal page with the slug listings, because it would clash with the ads archive.

Emails don’t arrive (sign-up, enquiries, password reset)

  1. Check the spam folder.
  2. Many hosts block or limit the PHP mail function. Install an SMTP plugin (for example WP Mail SMTP or FluentSMTP) and send its test email.
  3. Use a From address on your own domain and add SPF/DKIM records as your mail provider explains.

Password reset says the link is invalid or expired

Each link works once and lasts 24 hours. Requesting a new link cancels older ones, so always use the newest email. If links never work, check that a caching or security plugin doesn’t cache the Forgot Password page or strip the key and login parts of the address. Exclude that page from caching.

A Stripe payment went through but the plan or boost isn’t active

  1. Open CityPost → Payments and look for the payment.
  2. Make sure the webhook URL and the Webhook Secret are set for the same mode (test or live) as your keys, with the event checkout.session.completed. In Stripe, Developers → Webhooks shows whether deliveries failed.
  3. The payment is also confirmed when the buyer returns to your site; if they closed the tab first, the webhook is what completes it. You can resend the event from Stripe and it is applied once only.
  4. If nothing else helps, give the plan from CityPost → Members → Manage or add a bonus credit, and email support with the Stripe session ID.

Maps don’t show or addresses aren’t found

  1. Maps use Google Maps. Paste your Google Maps API key in CityPost → Settings → Maps. With no key saved, maps are simply hidden.
  2. In Google Cloud, turn on the Maps JavaScript API, Places API and Geocoding API for that key, with billing enabled.
  3. If you restricted the key to websites, add your domain (with and without www). The Geocoding API needs a key that isn’t restricted to websites, because addresses are looked up by your server.
  4. An ad’s address is looked up the first time its map is shown and then saved. If an ad has no address, no map is shown for it.
  5. Cookie or privacy plugins that block third-party scripts can hide the map until the visitor accepts.

Still stuck?

Email admin@007aj.com.

8. Sample image credits

The 12 sample ad photos were created for CityPost and are released under the GNU GPL v2 or later, the same licence as the theme and plugin (GPL-compatible). They contain no logos or real brands. They ship inside the CityPost Core plugin (assets/sample/) and are copied into your Media Library only when you install the sample data, so no outside download is needed.

9. Login, sign-up and footer

  • CityPost Core adds its own Log in (/login/) and Sign up (/signup/) pages. Visits to wp-login.php are sent to /login/; administrators can still reach the dashboard at /wp-admin/ after logging in there.
  • The footer has no theme credit by default. To add your own line, open CityPost → Settings → General, switch on Show a footer credit line and type the text.

10. CityPost Core plugin

The theme handles the look of your site. Everything that stores data lives in the CityPost Core plugin: the Listings post type, categories and locations, the seller dashboard, log in and sign up, messages, favourites, compare, reviews, maps, membership plans, ad boosts, Stripe payments and the payments log. If you ever change theme, keep the plugin on and your data stays in place. Without the plugin the theme still works as a normal blog theme and shows a notice recommending the plugin.

  • The admin menu CityPost → Documentation (and Appearance → CityPost Setup) opens this guide.
  • CityPost → Payments lists every payment, 50 per page.
  • Expired boosts are cleared by a daily background job that works in small batches, so it stays fast on large sites.
  • Calls to Stripe and Google geocoding are rate limited and pause automatically if the service asks the site to slow down.

11. Privacy

CityPost Core connects to Tools → Export Personal Data and Tools → Erase Personal Data. Exports include messages a person sent, their payments, favourites and membership history. Erasing deletes their messages, favourites and membership history, and unlinks their payments from their account (amounts and dates are kept for your records). Suggested wording is added to Settings → Privacy → Policy Guide.

12. Translation

Translation templates are in languages/citypost.pot (theme) and citypost-core/languages/citypost-core.pot (plugin). Put your .mo files in wp-content/languages/themes/ and wp-content/languages/plugins/.

13. Support

Need help? Email admin@007aj.com with your site address, the theme version (Appearance → Themes) and a short description or screenshot of the problem. We reply within two working days.

Copyright

The theme is released under the GNU General Public License v2 or later. Category icons are standard Unicode emoji.