REST API Reference

Get Started

WB Ad Manager Pro exposes a comprehensive set of REST API endpoints under the wbam-pro/v1 namespace. There are 70+ routes across 9 API classes covering advertisers, wallet, campaigns, classifieds, analytics, rotation, packages, Stripe, and WooCommerce.

Authentication

All endpoints require authentication unless marked as Public. Two methods are supported:

// Using Application Passwords (recommended for server-to-server)
Authorization: Basic base64(username:application_password)

// Using nonce (for logged-in users on the same WordPress site)
X-WP-Nonce: {nonce}

Permission Levels

Level Description
Public No authentication required
Logged-in Any authenticated WordPress user
Advertiser Logged-in user with an advertiser profile
Owner Advertiser who owns the specific resource
Admin User with manage_options capability

Advertiser API

Manages advertiser profiles, stats, wallet info, transactions, and ads. Class: Advertiser_API.

Advertiser Endpoints (Logged-in)

Method Endpoint Description Permission
GET /advertiser/profile Get current user’s advertiser profile Logged-in
POST/PUT /advertiser/profile Update advertiser profile (company_name) Logged-in
GET /advertiser/stats Get advertiser dashboard stats (ads, campaigns, impressions, clicks, balance) Logged-in
GET /advertiser/wallet Get wallet balance and formatted totals Logged-in
GET /advertiser/transactions Get paginated transaction history Logged-in
GET /advertiser/ads Get advertiser’s ads with pagination Logged-in

Common parameters for advertiser endpoints:

  • user_id (integer, optional) — Admin-only. Specify another user’s ID to view their data.

Transaction list parameters:

  • page (integer, default: 1)
  • per_page (integer, default: 20, max: 100)
  • type (string, optional) — Filter by transaction type

Ads list parameters:

  • page (integer, default: 1)
  • per_page (integer, default: 10, max: 50)
  • status (string, optional) — Filter by post status

Advertiser Admin Endpoints

Method Endpoint Description Permission
GET /admin/advertisers List all advertisers with pagination, search, status filter Admin
GET /admin/advertisers/{id} Get single advertiser details Admin
POST/PUT /admin/advertisers/{id} Update advertiser (status, company_name, balance) Admin
DELETE /admin/advertisers/{id} Delete advertiser Admin

Admin list parameters:

  • page (integer, default: 1)
  • per_page (integer, default: 20)
  • status (string, optional)
  • search (string, optional)

Wallet API

Manages wallet balances, transactions, fund additions, and payment confirmations. Class: Wallet_API. Routes are only registered when the wallet module is enabled.

Wallet User Endpoints

Method Endpoint Description Permission
GET /wallet/balance Get current balance, pending credits/debits, available balance, currency Logged-in
GET /wallet/transactions Get paginated transaction history Logged-in
POST /wallet/add-funds Create a pending fund transaction and initiate payment Logged-in
POST /wallet/confirm-payment Verify payment with gateway and complete transaction Logged-in
GET /wallet/payment-methods Get list of enabled payment methods with configuration Logged-in

Add funds parameters:

  • amount (number, required, min: 1) — Amount to add
  • payment_method (string, required, enum: stripe, paypal, razorpay, woocommerce, manual)
  • notes (string, optional) — Notes for manual payment requests

Confirm payment parameters:

  • transaction_id (string, required)
  • payment_method (string, required)
  • payment_id (string, optional) — Gateway payment/order ID

Wallet Admin Endpoints

Method Endpoint Description Permission
GET /admin/wallets List all wallets with search and pagination Admin
GET /admin/wallets/{user_id} Get specific user’s wallet details and stats Admin
GET /admin/wallets/{user_id}/transactions Get specific user’s transaction history Admin
POST /admin/wallets/{user_id}/adjust Credit or debit a user’s wallet balance Admin
GET /admin/transactions List all transactions with filters Admin
GET /admin/transactions/stats Get transaction statistics for a period Admin

Adjust balance parameters:

  • amount (number, required)
  • type (string, required, enum: credit, debit)
  • reason (string, optional)

Transaction stats parameters:

  • period (string, enum: today, week, month, year, all, default: month)

Campaign API

Manages campaigns including creation, status changes, stats, and admin approval. Class: Campaign_API. Routes are only registered when the campaigns module is enabled.

Campaign User Endpoints

Method Endpoint Description Permission
GET /campaigns List current user’s campaigns with pagination and status filter Logged-in
POST /campaigns Create a new campaign Logged-in
GET /campaigns/{id} Get single campaign details Owner/Admin
POST/PUT /campaigns/{id} Update campaign (only if draft, pending, or paused) Owner/Admin
DELETE /campaigns/{id} Delete campaign (refunds reservation if applicable) Owner/Admin
POST /campaigns/{id}/pause Pause an active campaign Owner/Admin
POST /campaigns/{id}/resume Resume a paused campaign Owner/Admin
GET /campaigns/{id}/stats Get campaign performance stats with daily breakdown Owner/Admin

Create/update campaign parameters:

  • name (string, required for create)
  • ad_id (integer, optional)
  • package_id (integer, optional)
  • budget (number, min: 0)
  • pricing_model (string, enum: flat, cpm, cpc)
  • price_per_unit (number, min: 0)
  • impressions_limit (integer, min: 0)
  • clicks_limit (integer, min: 0)
  • start_date (string, date format)
  • end_date (string, date format)

Campaign stats parameters:

  • period (string, enum: today, week, month, year, default: week)

Campaign Admin Endpoints

Method Endpoint Description Permission
GET /admin/campaigns List all campaigns with filters Admin
POST /admin/campaigns/{id}/approve Approve and activate a campaign Admin
POST /admin/campaigns/{id}/reject Reject (cancel) a campaign Admin

Admin list parameters:

  • page (integer, default: 1)
  • per_page (integer, default: 20)
  • status (string, optional)
  • advertiser_id (integer, optional)

Reject parameters:

  • reason (string, optional)

Classified API

Manages classified listings with public browsing, user CRUD, and admin moderation. Class: Classified_API. Routes are only registered when the classifieds module is enabled.

Classified Public Endpoints

Method Endpoint Description Permission
GET /classifieds Browse active classifieds with search, category, price, and sort filters Public
GET /classifieds/{id} Get single classified (increments view count) Public
GET /classifieds/categories Get all classified categories Public
POST /classifieds/{id}/contact Send inquiry to seller via contact form Public

Browse parameters:

  • category (integer, optional) — Category term ID
  • location (string, optional)
  • search (string, optional)
  • min_price (number, optional)
  • max_price (number, optional)
  • sort (string, enum: newest, price_low, price_high, featured, default: newest)
  • page (integer, default: 1)
  • per_page (integer, default: 20, max: 100)

Contact seller parameters:

  • name (string, required)
  • email (string, required)
  • phone (string, optional)
  • message (string, required)

Classified User Endpoints

Method Endpoint Description Permission
GET /my/classifieds List current user’s classifieds with status counts Logged-in
POST /my/classifieds Create a new classified listing (charges wallet) Logged-in
GET /my/classifieds/{id} Get single owned classified Owner
POST/PUT /my/classifieds/{id} Update owned classified Owner
DELETE /my/classifieds/{id} Delete owned classified Owner
POST /my/classifieds/{id}/sold Mark classified as sold Owner
POST /my/classifieds/{id}/renew Renew expired classified with a package (charges wallet) Owner
POST /my/classifieds/{id}/upgrade Add upgrades like featured, highlighted, urgent, bump (charges wallet) Owner

Create classified parameters:

  • title (string, required)
  • description (string, required)
  • category_id (integer, required)
  • price (number, optional)
  • price_type (string, enum: fixed, negotiable, free, contact)
  • location (string, optional)
  • contact_method (string, enum: form, email, phone, both)
  • contact_email (string, optional)
  • contact_phone (string, optional)
  • images (array of integers, optional) — Attachment IDs
  • package_id (integer, required)
  • upgrades (array of strings, optional)

Renew parameters:

  • package_id (integer, required)

Upgrade parameters:

  • upgrades (array of strings, required, enum: featured, highlighted, urgent, bump)

Classified Admin Endpoints

Method Endpoint Description Permission
GET /admin/classifieds List all classifieds with filters Admin
GET /admin/classifieds/{id} Get single classified with full admin details Admin
POST/PUT /admin/classifieds/{id} Update any classified field Admin
DELETE /admin/classifieds/{id} Delete classified Admin
POST /admin/classifieds/{id}/approve Approve a pending classified Admin
POST /admin/classifieds/{id}/reject Reject a classified with optional reason Admin

Admin list parameters:

  • status (string, optional)
  • user_id (integer, optional)
  • category (integer, optional)
  • search (string, optional)
  • page (integer, default: 1)
  • per_page (integer, default: 20)

Analytics API

Provides analytics data for ad performance including overview, per-ad stats, charts, geographic and device breakdowns, and data export. Class: Analytics_API. All endpoints require Admin permission.

Method Endpoint Description Permission
GET /analytics/overview Aggregate stats: impressions, clicks, CTR, unique visitors, revenue, active ads Admin
GET /analytics/ads/{id} Per-ad stats with daily and raw data breakdowns Admin
GET /analytics/chart Time-series chart data for a specific metric Admin
GET /analytics/top-ads Top performing ads ranked by impressions, clicks, or CTR Admin
GET /analytics/geo Geographic breakdown of impressions and clicks by country Admin
GET /analytics/devices Device type breakdown (desktop, mobile, tablet) Admin
GET /analytics/export Export analytics data as CSV or JSON Admin

Common date parameters (all analytics endpoints):

  • start_date (string, Y-m-d format, default: 30 days ago)
  • end_date (string, Y-m-d format, default: today)

Chart parameters:

  • ad_id (integer, optional, default: 0 for all ads)
  • metric (string, enum: impressions, clicks, ctr, default: impressions)

Top ads parameters:

  • limit (integer, default: 10)
  • orderby (string, enum: impressions, clicks, ctr, default: impressions)

Export parameters:

  • format (string, enum: csv, json, default: csv)
  • ad_id (integer, optional, default: 0 for all ads)

Rotation API

Manages fair ad rotation with share-of-voice tracking and admin configuration. Class: Rotation_API. Routes are only registered when the rotation module is enabled.

Rotation Advertiser Endpoints

Method Endpoint Description Permission
GET /rotation/share Get advertiser’s share of voice across placements Advertiser
GET /rotation/log Get paginated rotation log for advertiser Advertiser
GET /rotation/export Export rotation log as CSV data Advertiser

Share of voice parameters:

  • placement (string, optional) — Filter to specific placement
  • date_range (string, enum: today, week, month, year, default: month)

Rotation log parameters:

  • date_range (string, enum: today, week, month, year, default: week)
  • page (integer, default: 1)
  • per_page (integer, default: 50, max: 100)

Rotation Admin Endpoints

Method Endpoint Description Permission
GET /admin/rotation/placement Get rotation stats for a specific placement Admin
GET /admin/rotation/settings Get rotation configuration Admin
POST/PUT /admin/rotation/settings Update rotation settings Admin

Placement stats parameters:

  • placement (string, required)
  • date_range (string, enum: today, week, month, year, default: month)

Update settings parameters:

  • enable_rotation (boolean)
  • rotation_model (string, enum: equal, budget_weighted)
  • rotation_ads_per_placement (object) — Per-placement ad limits
  • rotation_reset_period (string, enum: hourly, daily)

Package API

Manages ad packages with public listing and admin CRUD. Class: Package_API. Routes are only registered when the packages module is enabled.

Package Public Endpoints

Method Endpoint Description Permission
GET /packages List all active packages Public
GET /packages/{id} Get single active package details Public

Package Admin Endpoints

Method Endpoint Description Permission
GET /admin/packages List all packages (any status) with counts Admin
POST /admin/packages Create a new package Admin
GET /admin/packages/{id} Get single package with usage count Admin
POST/PUT /admin/packages/{id} Update package Admin
DELETE /admin/packages/{id} Delete package Admin
POST /admin/packages/{id}/duplicate Duplicate a package Admin
POST /admin/packages/reorder Reorder packages by sort order Admin
POST /admin/packages/create-defaults Create default starter packages Admin

Create/update package parameters:

  • name (string, required for create)
  • description (string, optional)
  • placements (array of strings, optional)
  • duration_days (integer, min: 1)
  • impressions_limit (integer, min: 0)
  • clicks_limit (integer, min: 0)
  • price (number, min: 0) — Flat-rate price
  • pricing_model (string, enum: flat, cpm, cpc)
  • price_per_unit (number, min: 0) — Price per impression/click
  • requires_approval (boolean)
  • max_ads (integer, min: 0)
  • status (string, enum: active, inactive, archived)

Reorder parameters:

  • order (array of integers, required) — Package IDs in desired order

Stripe Integration API

Handles Stripe payment intents, checkout sessions, and webhook processing. Class: Stripe_Integration.

Method Endpoint Description Permission
GET /stripe/config Get Stripe publishable key and test mode status Logged-in
POST /stripe/create-payment-intent Create a Stripe PaymentIntent for card payments Logged-in
POST /stripe/confirm-payment Verify and confirm a succeeded PaymentIntent, credit wallet Logged-in
POST /stripe/create-checkout-session Create a Stripe Checkout Session (hosted payment page) Logged-in
GET /stripe/checkout-success Handle redirect after successful Checkout, credit wallet Logged-in
POST /stripe/webhook Receive Stripe webhook events (payment_intent.succeeded, checkout.session.completed, charge.refunded) Public

Create payment intent parameters:

  • amount (number, required) — Amount in base currency units (validated against min/max from settings)

Confirm payment parameters:

  • payment_intent_id (string, required)

Create checkout session parameters:

  • amount (number, required)

Checkout success parameters:

  • session_id (string, required) — Stripe Checkout Session ID

Webhook URL: https://yoursite.com/wp-json/wbam-pro/v1/stripe/webhook

WooCommerce Integration API

Adds WooCommerce wallet top-up functionality via a virtual product. Class: WooCommerce_Integration. Only active when WooCommerce plugin is installed.

Method Endpoint Description Permission
POST /wallet/woocommerce-add-funds Add wallet credit product to WooCommerce cart with custom amount Logged-in

Parameters:

  • amount (number, required) — Credit amount to add

Response includes:

  • cart_url — WooCommerce cart URL
  • checkout_url — WooCommerce checkout URL

Wallet credits are automatically applied when the WooCommerce order status changes to completed or processing. Refunds are handled when the order status changes to refunded.

Error Responses

All endpoints return standard WordPress REST API error responses:

{
    "code": "rest_forbidden",
    "message": "Sorry, you are not allowed to do that.",
    "data": {
        "status": 403
    }
}

Common error codes:

Code Status Description
rest_forbidden 403 User lacks permission for this action
rest_not_logged_in 401 User is not authenticated
rest_not_found / not_found 404 Requested resource does not exist
rest_invalid_param 400 A required parameter is missing or invalid
insufficient_balance 400 Advertiser wallet balance is too low
invalid_status 400 Resource is not in a valid state for the requested action
campaign_not_editable 400 Campaign cannot be edited in its current status
advertiser_not_found 404 No advertiser profile found for the user

Module Availability

Several API classes check whether their module is enabled before registering routes. If a module is disabled in Settings > Modules, its API endpoints will not be available:

Module API Class Setting Key
Wallet Wallet_API wallet
Campaigns Campaign_API campaigns
Classifieds Classified_API classifieds
Rotation Rotation_API rotation
Packages Package_API packages

The Advertiser, Analytics, Stripe, and WooCommerce APIs are always available when their respective integrations are configured.

Last updated: March 4, 2026