REST API
Bannerize exposes its data through the standard WordPress REST API. Because banners are stored as a custom post type (wp_bannerize) and campaigns as a custom taxonomy (wp_bannerize_tax), all standard WordPress REST endpoints are available. Additionally, all banner meta fields are exposed in the API response.
Authentication
The Bannerize REST API follows WordPress REST API authentication conventions:
- Public endpoints (GET requests for published banners) are accessible without authentication
- Write endpoints (POST, PUT, DELETE) require authentication with appropriate capabilities
Authentication methods:
- Cookie authentication — automatic when making requests from the WordPress admin (includes nonce)
- Application passwords — WordPress 5.6+ built-in feature for external applications
- OAuth / JWT — via third-party plugins
For external integrations, Application Passwords are the recommended authentication method. Generate one from Users > Profile > Application Passwords in the WordPress admin.
Banners Endpoints
The banner custom post type (wp_bannerize) is accessible at:
/wp-json/wp/v2/wp_bannerizeList All Banners
GET /wp-json/wp/v2/wp_bannerizeQuery Parameters:
| Parameter | Type | Description |
|---|---|---|
per_page | int | Number of results per page (default: 10, max: 100) |
page | int | Page number for pagination |
search | string | Search banners by title |
orderby | string | Sort field: date, title, modified, menu_order |
order | string | Sort direction: asc or desc |
wp_bannerize_tax | int | Filter by campaign term ID |
status | string | Post status: publish, draft, pending, private |
Example Request:
curl "https://yoursite.com/wp-json/wp/v2/wp_bannerize?per_page=5&orderby=date&order=desc"Get a Single Banner
GET /wp-json/wp/v2/wp_bannerize/{id}Example Request:
curl "https://yoursite.com/wp-json/wp/v2/wp_bannerize/42"Create a Banner
POST /wp-json/wp/v2/wp_bannerizeRequires authentication with manage_banners capability.
Body Parameters:
| Parameter | Type | Description |
|---|---|---|
title | string | Banner title |
content | string | HTML content (for HTML banners) |
status | string | Post status: publish, draft |
meta | object | Banner meta fields (see below) |
wp_bannerize_tax | array | Campaign term IDs |
Example Request:
curl -X POST "https://yoursite.com/wp-json/wp/v2/wp_bannerize" \
-H "Content-Type: application/json" \
-H "Authorization: Basic BASE64_ENCODED_CREDENTIALS" \
-d '{
"title": "Summer Sale Banner",
"status": "publish",
"meta": {
"banner_type": "remote",
"banner_external_url": "https://cdn.example.com/summer-sale.jpg",
"banner_width": 728,
"banner_height": 90,
"banner_description": "Summer sale - 50% off everything",
"banner_link": "https://example.com/sale",
"banner_target": "_blank",
"banner_no_follow": true,
"banner_impressions_enabled": true,
"banner_clicks_enabled": true
},
"wp_bannerize_tax": [5, 12]
}'Update a Banner
PUT /wp-json/wp/v2/wp_bannerize/{id}Requires authentication with manage_banners capability. Only include fields you want to update.
curl -X PUT "https://yoursite.com/wp-json/wp/v2/wp_bannerize/42" \
-H "Content-Type: application/json" \
-H "Authorization: Basic BASE64_ENCODED_CREDENTIALS" \
-d '{
"meta": {
"banner_link": "https://example.com/new-landing-page",
"banner_max_impressions": 10000
}
}'Delete a Banner
DELETE /wp-json/wp/v2/wp_bannerize/{id}Requires authentication with manage_banners capability.
curl -X DELETE "https://yoursite.com/wp-json/wp/v2/wp_bannerize/42" \
-H "Authorization: Basic BASE64_ENCODED_CREDENTIALS"By default, DELETE moves the banner to trash. Add ?force=true to permanently delete it.
Banner Meta Fields
All banner meta fields are exposed in the REST API response under the meta object:
| Field | Type | Description |
|---|---|---|
banner_type | string | Banner type: local, remote, or text |
banner_url | string | Local image URL (from media library) |
banner_external_url | string | Remote image URL |
banner_mime_type | string | Image MIME type (e.g., image/jpeg) |
banner_width | int | Banner width in pixels |
banner_height | int | Banner height in pixels |
banner_description | string | Alt text / description |
banner_link | string | Destination URL when clicked |
banner_target | string | Link target: _self, _blank, _parent, _top |
banner_no_follow | bool | Whether to add rel="nofollow" |
banner_date_from | string | Start date for scheduling (Y-m-d format) |
banner_date_expiry | string | End date for scheduling (Y-m-d format) |
banner_max_impressions | int | Maximum impressions (0 = unlimited) |
banner_max_clicks | int | Maximum clicks (0 = unlimited) |
banner_impressions_enabled | bool | Whether impression tracking is enabled |
banner_clicks_enabled | bool | Whether click tracking is enabled |
Campaigns Endpoints
The campaign taxonomy (wp_bannerize_tax) is accessible at:
/wp-json/wp/v2/wp_bannerize_taxList All Campaigns
GET /wp-json/wp/v2/wp_bannerize_taxQuery Parameters:
| Parameter | Type | Description |
|---|---|---|
per_page | int | Number of results per page |
page | int | Page number |
search | string | Search campaigns by name |
orderby | string | Sort field: name, slug, count |
order | string | Sort direction: asc or desc |
hide_empty | bool | Whether to hide campaigns with no banners |
Example Request:
curl "https://yoursite.com/wp-json/wp/v2/wp_bannerize_tax"Get a Single Campaign
GET /wp-json/wp/v2/wp_bannerize_tax/{id}Create a Campaign
POST /wp-json/wp/v2/wp_bannerize_taxcurl -X POST "https://yoursite.com/wp-json/wp/v2/wp_bannerize_tax" \
-H "Content-Type: application/json" \
-H "Authorization: Basic BASE64_ENCODED_CREDENTIALS" \
-d '{
"name": "Holiday Promotions",
"slug": "holiday-promotions",
"description": "All holiday season promotional banners"
}'Update a Campaign
PUT /wp-json/wp/v2/wp_bannerize_tax/{id}Delete a Campaign
DELETE /wp-json/wp/v2/wp_bannerize_tax/{id}Add ?force=true to permanently delete (taxonomy terms do not support trash).
Response Format
API responses follow the standard WordPress REST API format. A banner response looks like:
{
"id": 42,
"date": "2026-04-01T10:30:00",
"modified": "2026-04-05T14:20:00",
"slug": "summer-sale-banner",
"status": "publish",
"title": {
"rendered": "Summer Sale Banner"
},
"content": {
"rendered": "",
"protected": false
},
"meta": {
"banner_type": "remote",
"banner_external_url": "https://cdn.example.com/summer-sale.jpg",
"banner_width": 728,
"banner_height": 90,
"banner_description": "Summer sale - 50% off",
"banner_link": "https://example.com/sale",
"banner_target": "_blank",
"banner_no_follow": true,
"banner_date_from": "",
"banner_date_expiry": "",
"banner_max_impressions": 0,
"banner_max_clicks": 0,
"banner_impressions_enabled": true,
"banner_clicks_enabled": true
},
"wp_bannerize_tax": [5, 12],
"_links": {
"self": [{"href": "https://yoursite.com/wp-json/wp/v2/wp_bannerize/42"}],
"collection": [{"href": "https://yoursite.com/wp-json/wp/v2/wp_bannerize"}]
}
}Pagination
List endpoints return pagination headers:
| Header | Description |
|---|---|
X-WP-Total | Total number of items |
X-WP-TotalPages | Total number of pages |
Navigate pages with the page query parameter:
curl "https://yoursite.com/wp-json/wp/v2/wp_bannerize?page=2&per_page=10"The REST API does not directly expose analytics data (impressions, clicks, CTR). Analytics endpoints are internal to the plugin’s admin interface. To access analytics programmatically, use the CSV or SQL export features described in Reports.
