{"openapi": "3.0.3", "info": {"title": "Publisher Champ API", "version": "v1", "description": "\nBuild reporting workflows from the same publishing data that powers Publisher Champ.\n\nUse the focused analytics endpoints for ready-made reports, or use **Power Table** to\nchoose dimensions and measures, build nested breakdowns, and filter the result.\n\n## Quick start\n\n1. Open the API Access section of your Publisher Champ profile and copy your credentials.\n2. Call **Accounts \u2192 List accounts** and choose an `account_id`.\n3. Call an analytics endpoint or **Power Table \u2192 Query the Power Table**.\n\n**Base URL:** `https://www.publisherchamp.com/api/v1/`\n**Rate limit:** 20 requests per minute per API key, with at least 3 seconds between requests.\n\n```bash\ncurl \"https://www.publisherchamp.com/api/v1/performanceTableAPI/?api_key=YOUR_API_KEY&account_id=YOUR_ACCOUNT_ID&dimensions=title&measures=gross_royalties,total_paid_units\"\n```\n\n---\n\n## How to obtain API access\n\n<div class=\"publisher-champ-api-access-warning\"><strong>Upcoming change:</strong> From September 1, 2026, API access will be included with the Publisher Champ Ultra plan. Ultra pricing will be announced in mid-August 2026. Until September 1, the separate-account access method below remains in effect.</div>\n\n1. Create a second Publisher Champ account that will be used only for API access verification.\n   - You do not need to sync data or complete any other setup on this second account. It only needs an active subscription.\n   - If helpful, use an address such as `<your-email>+api@<your-domain>`. This normally reaches the same inbox while clearly identifying the API account. If your email provider does not support `+` aliases, use another email address you control.\n2. Add an active paid monthly or annual subscription to the second account.\n3. Email [support@publisherchamp.com](mailto:support@publisherchamp.com) or contact us through live chat after the subscription is active. We will enable API access for your main account, usually within a few hours.\n4. Once enabled, sign in to the dedicated API account you created, open **Profile \u2192 API Access**, and copy that account's `api_key` and `account_id`.\n\nUse **Accounts \u2192 List accounts** when you need to see every account available to the\nAPI key.\n"}, "paths": {"/api/v1/AMZAttributionStatsAPI/": {"get": {"operationId": "AMZAttributionStatsAPI_retrieve", "description": "Returns royalties and spend grouped by country or marketplace for the requested date range.\n\nFull URL: `https://www.publisherchamp.com/api/v1/countryStatsAPI/`\n\n<details>\n<summary><strong>Top-level fields</strong></summary>\n\nTop-level fields:\n\n| Field | Meaning |\n| --- | --- |\n| `countries` | Country breakdown keyed by country name. |\n| `global_earnings` | Total earnings across all included countries. |\n| `global_spend` | Total spend across all included countries. |\n| `global_amz_spend` | Total Amazon Ads spend across all included countries. |\n| `global_ad_sales` | Total ad-attributed sales across all included countries. |\n| `converted_currency` | Currency used for converted values in the response. |\n| `start_date` | The start date the returned data covers. |\n| `end_date` | The end date the returned data covers. |\n</details>\n\n<details>\n<summary><strong>Country row fields</strong></summary>\n\nEach item in `countries`:\n\n| Field | Meaning |\n| --- | --- |\n| `original` | Total earnings in the original marketplace currency. |\n| `converted` | Total earnings converted to the response currency. |\n| `original_currency` | Original currency for the marketplace or country. |\n| `converted_currency` | Currency used for converted values in the response. |\n| `original_spend` | Total spend in the original marketplace currency. |\n| `converted_spend` | Total spend converted to the response currency. |\n| `converted_amz_spend` | Amazon Ads spend converted to the response currency. |\n| `converted_ad_sales` | Ad-attributed sales converted to the response currency. |\n</details>", "summary": "List Amazon Attribution performance stats for an account", "parameters": [{"in": "query", "name": "account_id", "schema": {"type": "string"}, "description": "Account UUID associated with the API key.", "required": true}, {"in": "query", "name": "api_key", "schema": {"type": "string"}, "description": "Your unique API key.", "required": true}, {"in": "query", "name": "breakdown", "schema": {"type": "string", "enum": ["daily", "monthly"]}, "description": "Optional granularity: `daily` or `monthly`. When omitted, the standard non-breakdown response is returned. If any part of the range requires historical monthly data, the entire breakdown is returned monthly. Breakdown responses include the effective `granularity`."}, {"in": "query", "name": "countries", "schema": {"type": "string"}, "description": "Optional comma-separated marketplace/country filter. Use country codes like US, UK (or GB), DE, FR, ES, IT, NL, JP, IN, CA, BR, MX, AU, BE, IE, AE, SA, SE, PL, or special values Facebook, Other. Marketplace names (for example Amazon.com, Amazon.co.uk) are also accepted and normalized. Empty value (countries=) means all marketplaces."}, {"in": "query", "name": "currency", "schema": {"type": "string"}, "description": "Optional 3-letter currency code for response values, for example USD, EUR, or GBP."}, {"in": "query", "name": "end_date", "schema": {"type": "string", "format": "date"}, "description": "End date (YYYY-MM-DD). Must be within 365 days of start_date.", "required": true}, {"in": "query", "name": "fixed_range_selection", "schema": {"type": "string", "enum": ["Last 30 days", "Last 7 days", "Last 90 days", "Last Month", "Last Week", "Last Year", "This Month", "This Week", "This Year", "Today", "Yesterday"]}, "description": "Optional range shortcut."}, {"in": "query", "name": "start_date", "schema": {"type": "string", "format": "date"}, "description": "Start date (YYYY-MM-DD). The requested date range cannot exceed 365 days.", "required": true}], "tags": ["Advertising"], "responses": {"200": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/CountryStatsResponse"}, "examples": {"ExampleResponse": {"value": {"countries": {"United States": {"original": 463.51, "converted": 463.51, "original_currency": "USD", "converted_currency": "USD", "original_spend": 121.3, "converted_spend": 121.3, "converted_amz_spend": 95.0, "converted_ad_sales": 214.8}, "United Kingdom": {"original": 198.23, "converted": 252.14, "original_currency": "GBP", "converted_currency": "USD", "original_spend": 48.1, "converted_spend": 61.2, "converted_amz_spend": 42.7, "converted_ad_sales": 96.4}}, "global_earnings": 715.65, "global_spend": 182.5, "global_amz_spend": 137.7, "global_ad_sales": 311.2, "start_date": "2025-02-01", "end_date": "2025-02-28"}, "summary": "Example response"}}}}, "description": "Successful response"}, "400": {"content": {"application/json": {"schema": {"type": "object", "additionalProperties": {}}, "examples": {"ValidationError": {"value": {"error": "Invalid api_key format"}, "summary": "Validation error"}}}}, "description": "Validation error"}, "401": {"content": {"application/json": {"schema": {"type": "object", "additionalProperties": {}}, "examples": {"AuthenticationError": {"value": {"error": "api_key is invalid"}, "summary": "Authentication error"}}}}, "description": "Authentication error"}, "403": {"content": {"application/json": {"schema": {"type": "object", "additionalProperties": {}}, "examples": {"SubscriptionError": {"value": {"error": "User subscription is not valid (you need an active subscription to access the API). Login and update your subscription to regain API access."}, "summary": "Subscription error"}}}}, "description": "Subscription or access error"}, "429": {"content": {"application/json": {"schema": {"type": "object", "additionalProperties": {}}, "examples": {"RateLimitExceeded": {"value": {"error": "Rate limit exceeded. Maximum 20 requests per minute per API key, with at least 3 seconds between requests.", "limit": "20 requests per minute per API key; maximum 1 request every 3 seconds"}, "summary": "Rate limit exceeded"}}}}, "description": "Rate limit exceeded"}}}}, "/api/v1/JournalEventsAPI/": {"get": {"operationId": "JournalEventsAPI_retrieve", "description": "\nReturns all journal events belonging to the requested Publisher Champ account, ordered by event date (newest first).\n\nFull URL: `https://www.publisherchamp.com/api/v1/JournalEventsAPI/`\n\nThe `date` field is always returned in `YYYY-MM-DD` format. The `title` and `asin` fields identify the related book. Events that are not associated with a title return `null` for these fields.\n\n**cURL example**\n\n```bash\ncurl \"https://www.publisherchamp.com/api/v1/JournalEventsAPI/?api_key=<API_KEY>&account_id=<ACCOUNT_UUID>\"\n```\n\n**Python example**\n\n```python\nimport requests\n\nresponse = requests.get(\n    \"https://www.publisherchamp.com/api/v1/JournalEventsAPI/\",\n    params={\"api_key\": \"<API_KEY>\", \"account_id\": \"<ACCOUNT_UUID>\"},\n)\nresponse.raise_for_status()\njournal_events = response.json()[\"journal_events\"]\n```\n", "summary": "List journal events for an account", "parameters": [{"in": "query", "name": "account_id", "schema": {"type": "string"}, "description": "Account UUID associated with the API key.", "required": true}, {"in": "query", "name": "api_key", "schema": {"type": "string"}, "description": "Your unique API key.", "required": true}], "tags": ["Journal"], "responses": {"200": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/JournalEventsResponse"}, "examples": {"ExampleResponse": {"value": {"total_results": 2, "journal_events": [{"date": "2026-07-10", "tooltip": "Newsletter promotion", "description": "Featured the series starter in the weekly newsletter.", "annotate_on_graphs": true, "annotation_color": "#4E73DF", "title": "Example Book Title", "asin": "B000000001"}, {"date": "2026-07-01", "tooltip": "Website redesign launched", "description": "Published the new author website.", "annotate_on_graphs": false, "annotation_color": "#1CC88A", "title": null, "asin": null}]}, "summary": "Example response"}}}}, "description": "Successful response"}, "400": {"content": {"application/json": {"schema": {"type": "object", "additionalProperties": {}}, "examples": {"ValidationError": {"value": {"error": "Invalid api_key format"}, "summary": "Validation error"}}}}, "description": "Validation error"}, "401": {"content": {"application/json": {"schema": {"type": "object", "additionalProperties": {}}, "examples": {"AuthenticationError": {"value": {"error": "api_key is invalid"}, "summary": "Authentication error"}}}}, "description": "Authentication error"}, "403": {"content": {"application/json": {"schema": {"type": "object", "additionalProperties": {}}, "examples": {"SubscriptionError": {"value": {"error": "User subscription is not valid (you need an active subscription to access the API). Login and update your subscription to regain API access."}, "summary": "Subscription error"}}}}, "description": "Subscription or access error"}, "429": {"content": {"application/json": {"schema": {"type": "object", "additionalProperties": {}}, "examples": {"RateLimitExceeded": {"value": {"error": "Rate limit exceeded. Maximum 20 requests per minute per API key, with at least 3 seconds between requests.", "limit": "20 requests per minute per API key; maximum 1 request every 3 seconds"}, "summary": "Rate limit exceeded"}}}}, "description": "Rate limit exceeded"}}}}, "/api/v1/adsMonitoringAPI/": {"get": {"operationId": "adsMonitoringAPI_retrieve", "description": "Returns ad performance metrics grouped by ASIN or title for the requested date range.\n\nFull URL: `https://www.publisherchamp.com/api/v1/adsMonitoringAPI/`\n\n<details>\n<summary><strong>Top-level fields</strong></summary>\n\nTop-level fields:\n\n| Field | Meaning |\n| --- | --- |\n| `table_data` | Ad performance breakdown keyed by ASIN or grouped title reference. |\n| `start_date` | The start date the returned data covers. |\n| `end_date` | The end date the returned data covers. |\n</details>\n\n<details>\n<summary><strong>Ad row fields</strong></summary>\n\nEach item in `table_data`:\n\n| Field | Meaning |\n| --- | --- |\n| `number_of_ads` | Number of ads associated with this book or grouped reference. |\n| `spend` | Total ad spend across included ad sources. |\n| `amz_spend` | Amazon Ads spend. |\n| `impressions` | Total ad impressions. |\n| `clicks` | Total ad clicks. |\n| `ctr` | Click-through rate. |\n| `cpc` | Average cost per click. |\n| `orders` | Orders reported by the ad platform. |\n| `sales` | Sales attributed to ads. |\n| `acos` | Advertising cost of sales. |\n| `kenp_read` | Kindle Unlimited pages read attributed to ads. |\n| `estimated_kenp_royalties` | Estimated royalties from ad-attributed Kindle Unlimited reads. |\n| `title` | Book title. |\n| `tacos` | Total advertising cost of sales. |\n| `asin` | Book ASIN or grouped identifier. |\n| `currency` | Currency used for monetary amounts in this row. |\n| `all_asins` | All ASINs associated with this grouped row. |\n| `all_formats` | All formats associated with this grouped row. |\n| `actual_orders` | Actual orders from the underlying sales data. |\n| `reported_cr` | Conversion rate reported by the ad platform. |\n| `total_cr` | Conversion rate based on actual orders. |\n| `gross_revenue` | Gross revenue before deducting ad spend. |\n| `net_revenue` | Revenue after deducting ad spend. |\n| `roi` | Overall return on investment percentage. |\n| `ads_roi` | Amazon Ads return on investment percentage. |\n| `image` | Rendered image HTML for the book cover. |\n</details>", "summary": "List advertising performance stats for an account", "parameters": [{"in": "query", "name": "account_id", "schema": {"type": "string"}, "description": "Account UUID associated with the API key.", "required": true}, {"in": "query", "name": "api_key", "schema": {"type": "string"}, "description": "Your unique API key.", "required": true}, {"in": "query", "name": "breakdown", "schema": {"type": "string", "enum": ["daily", "monthly"]}, "description": "Optional granularity: `daily` or `monthly`. When omitted, the standard non-breakdown response is returned. If any part of the range requires historical monthly data, the entire breakdown is returned monthly. Breakdown responses include the effective `granularity`."}, {"in": "query", "name": "countries", "schema": {"type": "string"}, "description": "Optional comma-separated marketplace/country filter. Use country codes like US, UK (or GB), DE, FR, ES, IT, NL, JP, IN, CA, BR, MX, AU, BE, IE, AE, SA, SE, PL, or special values Facebook, BookBub. Marketplace names (for example Amazon.com, Amazon.co.uk) are also accepted and normalized. Empty value (countries=) means all marketplaces."}, {"in": "query", "name": "currency", "schema": {"type": "string"}, "description": "Optional 3-letter currency code for response values, for example USD, EUR, or GBP."}, {"in": "query", "name": "end_date", "schema": {"type": "string", "format": "date"}, "description": "End date (YYYY-MM-DD). Must be within 365 days of start_date.", "required": true}, {"in": "query", "name": "fixed_range_selection", "schema": {"type": "string", "enum": ["Last 30 days", "Last 7 days", "Last 90 days", "Last Month", "Last Week", "Last Year", "This Month", "This Week", "This Year", "Today", "Yesterday"]}, "description": "Optional range shortcut."}, {"in": "query", "name": "start_date", "schema": {"type": "string", "format": "date"}, "description": "Start date (YYYY-MM-DD). The requested date range cannot exceed 365 days.", "required": true}], "tags": ["Advertising"], "responses": {"200": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/AdsMonitoringResponse"}, "examples": {"ExampleResponse": {"value": {"table_data": {"B000000001": {"number_of_ads": 3, "spend": 12.3, "amz_spend": 10.1, "impressions": 3200, "clicks": 95, "ctr": "2.97%", "cpc": 0.13, "orders": 6, "sales": 78.4, "acos": "15.69%", "kenp_read": 1400, "estimated_kenp_royalties": 8.25, "title": "Second Book", "tacos": "11.55%", "asin": "B000000001", "currency": "USD", "all_asins": ["B000000001", "B000000099"], "all_formats": ["EBook", "Paperback"], "actual_orders": 9, "reported_cr": "6%", "total_cr": "9.47%", "gross_revenue": 106.5, "net_revenue": 94.2, "roi": 765, "ads_roi": 757, "image": "<img class=\"lazyload book-cover-3d\" loading=\"lazy\" data-src=\"https://example.com/covers/second-book.jpg\" style=\"max-width: 100px; max-height: 160px;\">"}, "B000000002": {"number_of_ads": 5, "spend": 28.9, "amz_spend": 26.0, "impressions": 7600, "clicks": 210, "ctr": "2.76%", "cpc": 0.14, "orders": 11, "sales": 155.2, "acos": "18.62%", "kenp_read": 4200, "estimated_kenp_royalties": 16.75, "title": "Third Book", "tacos": "14.34%", "asin": "B000000002", "currency": "USD", "all_asins": ["B000000002"], "all_formats": ["EBook"], "actual_orders": 15, "reported_cr": "5%", "total_cr": "7.14%", "gross_revenue": 201.6, "net_revenue": 172.7, "roi": 597, "ads_roi": 561, "image": "<img class=\"lazyload book-cover-3d\" loading=\"lazy\" data-src=\"https://example.com/covers/third-book.jpg\" style=\"max-width: 100px; max-height: 160px;\">"}}, "start_date": "2025-02-01", "end_date": "2025-02-28"}, "summary": "Example response"}}}}, "description": "Successful response"}, "400": {"content": {"application/json": {"schema": {"type": "object", "additionalProperties": {}}, "examples": {"ValidationError": {"value": {"error": "Invalid api_key format"}, "summary": "Validation error"}}}}, "description": "Validation error"}, "401": {"content": {"application/json": {"schema": {"type": "object", "additionalProperties": {}}, "examples": {"AuthenticationError": {"value": {"error": "api_key is invalid"}, "summary": "Authentication error"}}}}, "description": "Authentication error"}, "403": {"content": {"application/json": {"schema": {"type": "object", "additionalProperties": {}}, "examples": {"SubscriptionError": {"value": {"error": "User subscription is not valid (you need an active subscription to access the API). Login and update your subscription to regain API access."}, "summary": "Subscription error"}}}}, "description": "Subscription or access error"}, "429": {"content": {"application/json": {"schema": {"type": "object", "additionalProperties": {}}, "examples": {"RateLimitExceeded": {"value": {"error": "Rate limit exceeded. Maximum 20 requests per minute per API key, with at least 3 seconds between requests.", "limit": "20 requests per minute per API key; maximum 1 request every 3 seconds"}, "summary": "Rate limit exceeded"}}}}, "description": "Rate limit exceeded"}}}}, "/api/v1/amazonAttributionAdTagsAPI/": {"post": {"operationId": "amazonAttributionAdTagsAPI_create", "description": "Returns Amazon Attribution ad tags for the requested account.\n\nFull URL: `https://www.publisherchamp.com/api/v1/amazonAttributionAdTagsAPI/`\n\nThis endpoint is `POST` and accepts JSON. Use `search_q` to search within `attribution_id`.\n\n<details>\n<summary><strong>Request fields</strong></summary>\n\n| Field | Meaning |\n| --- | --- |\n| `api_key` | Publisher Champ API key. |\n| `account_id` | Publisher Champ account UUID. |\n| `search_q` | Optional substring search applied to `attribution_id`. |\n| `page` | Optional page number. Defaults to `1`. |\n| `length` | Optional rows per page. Defaults to `100` and cannot exceed `100`. |\n</details>\n\n<details>\n<summary><strong>Response fields</strong></summary>\n\n| Field | Meaning |\n| --- | --- |\n| `total_results` | Total rows matching the request. |\n| `page` | Returned page number. |\n| `length` | Rows requested per page. |\n| `total_pages` | Total available pages for the requested length. |\n| `table_data` | List of matching Amazon Attribution ad tag rows. |\n| `attribution_id` | Amazon Attribution id. |\n| `tag` | Amazon Attribution ad tag. |\n</details>", "summary": "List Amazon Attribution ad tags for an account", "tags": ["Advertising"], "requestBody": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/AmazonAttributionAdTagRequest"}}, "application/x-www-form-urlencoded": {"schema": {"$ref": "#/components/schemas/AmazonAttributionAdTagRequest"}}, "multipart/form-data": {"schema": {"$ref": "#/components/schemas/AmazonAttributionAdTagRequest"}}}, "required": true}, "responses": {"200": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/AmazonAttributionAdTagsResponse"}, "examples": {"ExampleResponse": {"value": {"total_results": 1, "page": 1, "length": 100, "total_pages": 1, "table_data": [{"attribution_id": "United States - 1234567890 - 99887766", "tag": "https://amazon.com/dp/publisherchamp-20?maas=...."}]}, "summary": "Example response"}}}}, "description": "Successful response"}, "400": {"content": {"application/json": {"schema": {"type": "object", "additionalProperties": {}}, "examples": {"ValidationError": {"value": {"error": "Invalid api_key format"}, "summary": "Validation error"}}}}, "description": "Validation error"}, "401": {"content": {"application/json": {"schema": {"type": "object", "additionalProperties": {}}, "examples": {"AuthenticationError": {"value": {"error": "api_key is invalid"}, "summary": "Authentication error"}}}}, "description": "Authentication error"}, "403": {"content": {"application/json": {"schema": {"type": "object", "additionalProperties": {}}, "examples": {"SubscriptionError": {"value": {"error": "User subscription is not valid (you need an active subscription to access the API). Login and update your subscription to regain API access."}, "summary": "Subscription error"}}}}, "description": "Subscription or access error"}, "429": {"content": {"application/json": {"schema": {"type": "object", "additionalProperties": {}}, "examples": {"RateLimitExceeded": {"value": {"error": "Rate limit exceeded. Maximum 20 requests per minute per API key, with at least 3 seconds between requests.", "limit": "20 requests per minute per API key; maximum 1 request every 3 seconds"}, "summary": "Rate limit exceeded"}}}}, "description": "Rate limit exceeded"}}}}, "/api/v1/authorStatsAPI/": {"get": {"operationId": "authorStatsAPI_retrieve", "description": "Returns per-author breakdowns for the requested date range.\n\nFull URL: `https://www.publisherchamp.com/api/v1/authorStatsAPI/`\n\n<details>\n<summary><strong>Top-level fields</strong></summary>\n\nTop-level fields:\n\n| Field | Meaning |\n| --- | --- |\n| `table_data` | Author breakdown keyed by author name. |\n| `start_date` | The start date the returned data covers. |\n| `end_date` | The end date the returned data covers. |\n</details>\n\n<details>\n<summary><strong>Author book row fields</strong></summary>\n\nEach book row under an author:\n\n| Field | Meaning |\n| --- | --- |\n| `units_sold` | Total units sold for this book under the author. |\n| `free_units_sold` | Number of free units sold or downloaded. |\n| `paid_units_sold` | Number of paid units sold. |\n| `book_royalty` | Royalties earned from book sales. |\n| `read_royalty` | Royalties earned from Kindle Unlimited reads. |\n| `reads` | Number of Kindle Unlimited page reads. |\n| `asin` | Book ASIN or internal grouped identifier. |\n| `currency` | Currency used for monetary amounts in this row. |\n| `external_royalty` | Royalty from external or manually added royalty sources. |\n| `book_title` | Book title. |\n</details>", "summary": "List author performance stats for an account", "parameters": [{"in": "query", "name": "account_id", "schema": {"type": "string"}, "description": "Account UUID associated with the API key.", "required": true}, {"in": "query", "name": "api_key", "schema": {"type": "string"}, "description": "Your unique API key.", "required": true}, {"in": "query", "name": "breakdown", "schema": {"type": "string", "enum": ["daily", "monthly"]}, "description": "Optional granularity: `daily` or `monthly`. When omitted, the standard non-breakdown response is returned. If any part of the range requires historical monthly data, the entire breakdown is returned monthly. Breakdown responses include the effective `granularity`."}, {"in": "query", "name": "currency", "schema": {"type": "string"}, "description": "Optional 3-letter currency code for response values, for example USD, EUR, or GBP."}, {"in": "query", "name": "end_date", "schema": {"type": "string", "format": "date"}, "description": "End date (YYYY-MM-DD). Must be within 365 days of start_date.", "required": true}, {"in": "query", "name": "fixed_range_selection", "schema": {"type": "string", "enum": ["Last 30 days", "Last 7 days", "Last 90 days", "Last Month", "Last Week", "Last Year", "This Month", "This Week", "This Year", "Today", "Yesterday"]}, "description": "Optional range shortcut."}, {"in": "query", "name": "start_date", "schema": {"type": "string", "format": "date"}, "description": "Start date (YYYY-MM-DD). The requested date range cannot exceed 365 days.", "required": true}], "tags": ["Analytics"], "responses": {"200": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/AuthorStatsResponse"}, "examples": {"ExampleResponse": {"value": {"table_data": {"Jane Doe": {"Example Book": {"units_sold": 140, "free_units_sold": 12, "paid_units_sold": 128, "book_royalty": 120.0, "read_royalty": 15.5, "reads": 500, "asin": "B000000000", "currency": "USD", "external_royalty": 4.25, "book_title": "Example Book"}}, "John Smith": {"Book A": {"units_sold": 80, "free_units_sold": 5, "paid_units_sold": 75, "book_royalty": 70.0, "read_royalty": 6.8, "reads": 120, "asin": "B000000100", "currency": "USD", "external_royalty": 0, "book_title": "Book A"}, "Book B": {"units_sold": 40, "free_units_sold": 0, "paid_units_sold": 40, "book_royalty": 45.5, "read_royalty": 3.2, "reads": 90, "asin": "B000000101", "currency": "USD", "external_royalty": 2.1, "book_title": "Book B"}}}, "start_date": "2025-02-01", "end_date": "2025-02-28"}, "summary": "Example response"}}}}, "description": "Successful response"}, "400": {"content": {"application/json": {"schema": {"type": "object", "additionalProperties": {}}, "examples": {"ValidationError": {"value": {"error": "Invalid api_key format"}, "summary": "Validation error"}}}}, "description": "Validation error"}, "401": {"content": {"application/json": {"schema": {"type": "object", "additionalProperties": {}}, "examples": {"AuthenticationError": {"value": {"error": "api_key is invalid"}, "summary": "Authentication error"}}}}, "description": "Authentication error"}, "403": {"content": {"application/json": {"schema": {"type": "object", "additionalProperties": {}}, "examples": {"SubscriptionError": {"value": {"error": "User subscription is not valid (you need an active subscription to access the API). Login and update your subscription to regain API access."}, "summary": "Subscription error"}}}}, "description": "Subscription or access error"}, "429": {"content": {"application/json": {"schema": {"type": "object", "additionalProperties": {}}, "examples": {"RateLimitExceeded": {"value": {"error": "Rate limit exceeded. Maximum 20 requests per minute per API key, with at least 3 seconds between requests.", "limit": "20 requests per minute per API key; maximum 1 request every 3 seconds"}, "summary": "Rate limit exceeded"}}}}, "description": "Rate limit exceeded"}}}}, "/api/v1/bookStatsAPI/": {"get": {"operationId": "bookStatsAPI_retrieve", "description": "Returns per-book sales, royalties, reads, and spend for the requested date range.\n\nFull URL: `https://www.publisherchamp.com/api/v1/bookStatsAPI/`\n\n<details>\n<summary><strong>Top-level fields</strong></summary>\n\nTop-level fields:\n\n| Field | Meaning |\n| --- | --- |\n| `table_data` | List of book-level rows, or a date-keyed object when `breakdown` is supplied. |\n| `start_date` | The start date the returned data covers. |\n| `end_date` | The end date the returned data covers. |\n| `breakdown` | Returned breakdown (`daily` or `monthly`), when supplied. |\n| `granularity` | Effective data granularity (`daily` or `monthly`). If any part of the range requires historical monthly data, all returned buckets are monthly. |\n</details>\n\n<details>\n<summary><strong>Book row fields</strong></summary>\n\nEach item in `table_data`:\n\n| Field | Meaning |\n| --- | --- |\n| `image` | Book cover image URL. |\n| `title` | Book title. |\n| `asin` | The book's unique identifier. |\n| `currency` | Currency used for all monetary amounts in this row. |\n| `ad_orders` | Number of inorganic orders attributed to Amazon Ads. |\n| `paperbacks_sold` | Number of paperback units sold. |\n| `paperbacks_royalties` | Royalties earned from paperback sales. |\n| `audiobooks_sold` | Number of audiobook units sold. |\n| `audiobooks_royalties` | Royalties earned from audiobook sales. |\n| `pre_orders_sold` | Number of pre-order units sold. |\n| `expanded_distribution_sold` | Number of expanded distribution units sold. |\n| `expanded_distribution_royalties` | Royalties earned from expanded distribution sales. |\n| `hardcovers_sold` | Number of hardcover units sold. |\n| `hardcovers_royalties` | Royalties earned from hardcover sales. |\n| `ebooks_paid_sold` | Number of paid ebook units sold. |\n| `ebooks_paid_royalties` | Royalties earned from paid ebook sales. |\n| `ebooks_free_sold` | Number of free ebook units downloaded. |\n| `total_reads` | Number of Kindle Unlimited page reads. |\n| `spending` | Total spend across Amazon Ads, Facebook/Meta Ads, and custom external expenses. |\n| `custom_expenses` | Amount spent on manually added external expenses, separate from ad spend. |\n| `amz_ad_spend` | Amount spent on Amazon Ads only, excluding Facebook/Meta Ads and custom external expenses. |\n| `fb_ad_spend` | Amount spent on Facebook/Meta Ads only, excluding Amazon Ads and custom external expenses. |\n| `gross_royalty` | Total royalty before deducting spend. |\n| `total_read_royalty` | Total royalty earned from Kindle Unlimited reads. |\n| `net_royalty` | Net royalty after subtracting spend from gross royalty. |\n| `published_date` | Book publication date. |\n| `full_reads` | Estimated whole-book borrows: floor(total reads divided by KENPC). |\n| `all_asins` | All ASINs associated with this grouped title. |\n| `all_formats` | All formats associated with this grouped title. |\n| `all_series` | All series values associated with this grouped title. |\n| `ad_clicks` | Total ad clicks from Amazon Ads and Facebook/Meta Ads combined. |\n| `fb_clicks` | Number of Facebook/Meta ad clicks. |\n| `amz_clicks` | Number of Amazon ad clicks. |\n| `clicks` | Number of Smart Link clicks. |\n| `country_breakdown` | Optional breakdown by country or marketplace. |\n| `platform_breakdown` | Optional breakdown by publishing platform. |\n</details>", "summary": "List book performance stats for an account", "parameters": [{"in": "query", "name": "account_id", "schema": {"type": "string"}, "description": "Account UUID associated with the API key.", "required": true}, {"in": "query", "name": "api_key", "schema": {"type": "string"}, "description": "Your unique API key.", "required": true}, {"in": "query", "name": "breakdown", "schema": {"type": "string", "enum": ["daily", "monthly"]}, "description": "Optional granularity: `daily` or `monthly`. When omitted, the standard non-breakdown response is returned. If any part of the range requires historical monthly data, the entire breakdown is returned monthly. Breakdown responses include the effective `granularity`."}, {"in": "query", "name": "countries", "schema": {"type": "string"}, "description": "Optional comma-separated marketplace/country filter. Use country codes like US, UK (or GB), DE, FR, ES, IT, NL, JP, IN, CA, BR, MX, AU, BE, IE, AE, SA, SE, PL, or special values Facebook, Other. Marketplace names (for example Amazon.com, Amazon.co.uk) are also accepted and normalized. Empty value (countries=) means all marketplaces."}, {"in": "query", "name": "currency", "schema": {"type": "string"}, "description": "Optional 3-letter currency code for response values, for example USD, EUR, or GBP."}, {"in": "query", "name": "end_date", "schema": {"type": "string", "format": "date"}, "description": "End date (YYYY-MM-DD). Must be within 365 days of start_date.", "required": true}, {"in": "query", "name": "fixed_range_selection", "schema": {"type": "string", "enum": ["Last 30 days", "Last 7 days", "Last 90 days", "Last Month", "Last Week", "Last Year", "This Month", "This Week", "This Year", "Today", "Yesterday"]}, "description": "Optional range shortcut."}, {"in": "query", "name": "include_country_breakdown", "schema": {"type": "boolean"}, "description": "Optional boolean. Set to true to include per-book country breakdowns in the response."}, {"in": "query", "name": "include_platform_breakdown", "schema": {"type": "boolean"}, "description": "Optional boolean. Set to true to include per-book platform breakdowns in the response."}, {"in": "query", "name": "start_date", "schema": {"type": "string", "format": "date"}, "description": "Start date (YYYY-MM-DD). The requested date range cannot exceed 365 days.", "required": true}], "tags": ["Analytics"], "responses": {"200": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/BookStatsResponse"}, "examples": {"ExampleResponse": {"value": {"table_data": [{"image": "https://example.com/covers/example-book.jpg", "title": "Example Book", "asin": "B000000000", "currency": "USD", "ad_orders": 8, "paperbacks_sold": 14, "paperbacks_royalties": 18.4, "audiobooks_sold": 3, "audiobooks_royalties": 9.25, "pre_orders_sold": 5, "expanded_distribution_sold": 2, "expanded_distribution_royalties": 3.8, "hardcovers_sold": 4, "hardcovers_royalties": 11.0, "ebooks_paid_sold": 120, "ebooks_paid_royalties": 81.28, "ebooks_free_sold": 7, "total_reads": 2450, "spending": 28.75, "custom_expenses": 4.0, "amz_ad_spend": 18.5, "fb_ad_spend": 6.25, "gross_royalty": 123.45, "total_read_royalty": 21.22, "net_royalty": 94.7, "published_date": "2024-06-15", "full_reads": 12, "all_asins": ["B000000000", "B000000010"], "all_formats": ["EBook", "Paperback"], "all_series": ["#1 in Example Series", "#1 in Example Series"], "ad_clicks": 42, "fb_clicks": 10, "amz_clicks": 32, "clicks": 55, "country_breakdown": {"US": {"read_royalty": 12.52, "book_royalty": 70.11}, "UK": {"read_royalty": 8.7, "book_royalty": 32.12}}, "platform_breakdown": {"Amazon": 92.5, "Shopify": 18.73, "Apple Books": 12.22}}, {"image": "https://example.com/covers/second-book.jpg", "title": "Second Book", "asin": "B000000001", "currency": "USD", "ad_orders": 3, "paperbacks_sold": 6, "paperbacks_royalties": 7.8, "audiobooks_sold": 1, "audiobooks_royalties": 3.1, "pre_orders_sold": 2, "expanded_distribution_sold": 1, "expanded_distribution_royalties": 1.7, "hardcovers_sold": 0, "hardcovers_royalties": 0.0, "ebooks_paid_sold": 40, "ebooks_paid_royalties": 29.4, "ebooks_free_sold": 4, "total_reads": 600, "spending": 9.5, "custom_expenses": 1.5, "amz_ad_spend": 8.0, "fb_ad_spend": 0.0, "gross_royalty": 54.0, "total_read_royalty": 9.0, "net_royalty": 44.5, "published_date": "2023-11-03", "full_reads": 3, "all_asins": ["B000000001"], "all_formats": ["EBook"], "all_series": ["#1 in My Series", "#1 in My Series"], "ad_clicks": 18, "fb_clicks": 5, "amz_clicks": 13, "clicks": 21, "country_breakdown": {"US": {"read_royalty": 4.1, "book_royalty": 38.5}, "UK": {"read_royalty": 1.9, "book_royalty": 9.5}}, "platform_breakdown": {"Amazon": 44.5, "Barnes & Noble Press": 6.1, "Apple Books": 3.4}}], "start_date": "2025-01-01", "end_date": "2025-01-31"}, "summary": "Example response"}}}}, "description": "Successful response"}, "400": {"content": {"application/json": {"schema": {"type": "object", "additionalProperties": {}}, "examples": {"ValidationError": {"value": {"error": "Invalid api_key format"}, "summary": "Validation error"}}}}, "description": "Validation error"}, "401": {"content": {"application/json": {"schema": {"type": "object", "additionalProperties": {}}, "examples": {"AuthenticationError": {"value": {"error": "api_key is invalid"}, "summary": "Authentication error"}}}}, "description": "Authentication error"}, "403": {"content": {"application/json": {"schema": {"type": "object", "additionalProperties": {}}, "examples": {"SubscriptionError": {"value": {"error": "User subscription is not valid (you need an active subscription to access the API). Login and update your subscription to regain API access."}, "summary": "Subscription error"}}}}, "description": "Subscription or access error"}, "429": {"content": {"application/json": {"schema": {"type": "object", "additionalProperties": {}}, "examples": {"RateLimitExceeded": {"value": {"error": "Rate limit exceeded. Maximum 20 requests per minute per API key, with at least 3 seconds between requests.", "limit": "20 requests per minute per API key; maximum 1 request every 3 seconds"}, "summary": "Rate limit exceeded"}}}}, "description": "Rate limit exceeded"}}}}, "/api/v1/countryStatsAPI/": {"get": {"operationId": "countryStatsAPI_retrieve", "description": "Returns royalties and spend grouped by country or marketplace for the requested date range.\n\nFull URL: `https://www.publisherchamp.com/api/v1/countryStatsAPI/`\n\n<details>\n<summary><strong>Top-level fields</strong></summary>\n\nTop-level fields:\n\n| Field | Meaning |\n| --- | --- |\n| `countries` | Country breakdown keyed by country name. |\n| `global_earnings` | Total earnings across all included countries. |\n| `global_spend` | Total spend across all included countries. |\n| `global_amz_spend` | Total Amazon Ads spend across all included countries. |\n| `global_ad_sales` | Total ad-attributed sales across all included countries. |\n| `converted_currency` | Currency used for converted values in the response. |\n| `start_date` | The start date the returned data covers. |\n| `end_date` | The end date the returned data covers. |\n</details>\n\n<details>\n<summary><strong>Country row fields</strong></summary>\n\nEach item in `countries`:\n\n| Field | Meaning |\n| --- | --- |\n| `original` | Total earnings in the original marketplace currency. |\n| `converted` | Total earnings converted to the response currency. |\n| `original_currency` | Original currency for the marketplace or country. |\n| `converted_currency` | Currency used for converted values in the response. |\n| `original_spend` | Total spend in the original marketplace currency. |\n| `converted_spend` | Total spend converted to the response currency. |\n| `converted_amz_spend` | Amazon Ads spend converted to the response currency. |\n| `converted_ad_sales` | Ad-attributed sales converted to the response currency. |\n</details>", "summary": "List country performance stats for an account", "parameters": [{"in": "query", "name": "account_id", "schema": {"type": "string"}, "description": "Account UUID associated with the API key.", "required": true}, {"in": "query", "name": "api_key", "schema": {"type": "string"}, "description": "Your unique API key.", "required": true}, {"in": "query", "name": "countries", "schema": {"type": "string"}, "description": "Optional comma-separated marketplace/country filter. Use country codes like US, UK (or GB), DE, FR, ES, IT, NL, JP, IN, CA, BR, MX, AU, BE, IE, AE, SA, SE, PL, or special values Facebook, Other. Marketplace names (for example Amazon.com, Amazon.co.uk) are also accepted and normalized. Empty value (countries=) means all marketplaces."}, {"in": "query", "name": "currency", "schema": {"type": "string"}, "description": "Optional 3-letter currency code for response values, for example USD, EUR, or GBP."}, {"in": "query", "name": "end_date", "schema": {"type": "string", "format": "date"}, "description": "End date (YYYY-MM-DD). Must be within 365 days of start_date.", "required": true}, {"in": "query", "name": "fixed_range_selection", "schema": {"type": "string", "enum": ["Last 30 days", "Last 7 days", "Last 90 days", "Last Month", "Last Week", "Last Year", "This Month", "This Week", "This Year", "Today", "Yesterday"]}, "description": "Optional range shortcut."}, {"in": "query", "name": "start_date", "schema": {"type": "string", "format": "date"}, "description": "Start date (YYYY-MM-DD). The requested date range cannot exceed 365 days.", "required": true}], "tags": ["Analytics"], "responses": {"200": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/CountryStatsResponse"}, "examples": {"ExampleResponse": {"value": {"countries": {"United States": {"original": 463.51, "converted": 463.51, "original_currency": "USD", "converted_currency": "USD", "original_spend": 121.3, "converted_spend": 121.3, "converted_amz_spend": 95.0, "converted_ad_sales": 214.8}, "United Kingdom": {"original": 198.23, "converted": 252.14, "original_currency": "GBP", "converted_currency": "USD", "original_spend": 48.1, "converted_spend": 61.2, "converted_amz_spend": 42.7, "converted_ad_sales": 96.4}}, "global_earnings": 715.65, "global_spend": 182.5, "global_amz_spend": 137.7, "global_ad_sales": 311.2, "start_date": "2025-02-01", "end_date": "2025-02-28"}, "summary": "Example response"}}}}, "description": "Successful response"}, "400": {"content": {"application/json": {"schema": {"type": "object", "additionalProperties": {}}, "examples": {"ValidationError": {"value": {"error": "Invalid api_key format"}, "summary": "Validation error"}}}}, "description": "Validation error"}, "401": {"content": {"application/json": {"schema": {"type": "object", "additionalProperties": {}}, "examples": {"AuthenticationError": {"value": {"error": "api_key is invalid"}, "summary": "Authentication error"}}}}, "description": "Authentication error"}, "403": {"content": {"application/json": {"schema": {"type": "object", "additionalProperties": {}}, "examples": {"SubscriptionError": {"value": {"error": "User subscription is not valid (you need an active subscription to access the API). Login and update your subscription to regain API access."}, "summary": "Subscription error"}}}}, "description": "Subscription or access error"}, "429": {"content": {"application/json": {"schema": {"type": "object", "additionalProperties": {}}, "examples": {"RateLimitExceeded": {"value": {"error": "Rate limit exceeded. Maximum 20 requests per minute per API key, with at least 3 seconds between requests.", "limit": "20 requests per minute per API key; maximum 1 request every 3 seconds"}, "summary": "Rate limit exceeded"}}}}, "description": "Rate limit exceeded"}}}}, "/api/v1/listAccountsAPI/": {"get": {"operationId": "listAccountsAPI_retrieve", "description": "Returns the accounts this API key can access.\n\nFull URL: `https://www.publisherchamp.com/api/v1/listAccountsAPI/`\n\n<details>\n<summary><strong>Top-level fields</strong></summary>\n\nTop-level fields:\n\n| Field | Meaning |\n| --- | --- |\n| `api_key` | The API key used for the request. |\n| `api_key_owner_email` | Email address of the API key owner. |\n| `accounts` | List of accounts accessible to this API key. |\n</details>\n\n<details>\n<summary><strong>Account row fields</strong></summary>\n\nEach item in `accounts`:\n\n| Field | Meaning |\n| --- | --- |\n| `account_id` | Account UUID. |\n| `user_email` | Email address of the account owner. |\n| `access_granted_at` | When access was granted, if applicable. |\n| `access_type` | How this account is accessible to the API key owner. |\n| `external_user_id` | Optional external user ID stored with the access grant. Omitted when not present. |\n</details>", "summary": "List accounts available to an API key", "parameters": [{"in": "query", "name": "api_key", "schema": {"type": "string"}, "description": "Your unique API key.", "required": true}], "tags": ["Accounts"], "responses": {"200": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/ListAccountsResponse"}, "examples": {"ExampleResponse": {"value": {"api_key": "<redacted>", "api_key_owner_email": "api-user@example.com", "accounts": [{"account_id": "<redacted>", "user_email": "api-user@example.com", "access_granted_at": null, "access_type": "owner"}, {"account_id": "<redacted>", "user_email": "client-one@example.com", "access_granted_at": "2026-03-21T11:42:18+00:00", "access_type": "explicit_grant", "external_user_id": "portal-user-123"}, {"account_id": "<redacted>", "user_email": "client-two@example.com", "access_granted_at": "2026-03-22T08:05:09+00:00", "access_type": "explicit_grant"}]}, "summary": "Example response"}}}}, "description": "Successful response"}, "400": {"content": {"application/json": {"schema": {"type": "object", "additionalProperties": {}}, "examples": {"ValidationError": {"value": {"error": "Invalid api_key format"}, "summary": "Validation error"}}}}, "description": "Validation error"}, "401": {"content": {"application/json": {"schema": {"type": "object", "additionalProperties": {}}, "examples": {"AuthenticationError": {"value": {"error": "api_key is invalid"}, "summary": "Authentication error"}}}}, "description": "Authentication error"}, "403": {"content": {"application/json": {"schema": {"type": "object", "additionalProperties": {}}, "examples": {"SubscriptionError": {"value": {"error": "User subscription is not valid (you need an active subscription to access the API). Login and update your subscription to regain API access."}, "summary": "Subscription error"}}}}, "description": "Subscription or access error"}, "429": {"content": {"application/json": {"schema": {"type": "object", "additionalProperties": {}}, "examples": {"RateLimitExceeded": {"value": {"error": "Rate limit exceeded. Maximum 20 requests per minute per API key, with at least 3 seconds between requests.", "limit": "20 requests per minute per API key; maximum 1 request every 3 seconds"}, "summary": "Rate limit exceeded"}}}}, "description": "Rate limit exceeded"}}}}, "/api/v1/performanceTableAPI/": {"get": {"operationId": "performanceTableAPI_retrieve", "description": "Build a custom, server-side pivot table across sales, royalties, reads, advertising, expenses, book metadata, and Journal Events.\n\n**Typical flow**\n\n1. Call this endpoint with `schema_only=1` to discover the dimensions and measures available to the account.\n2. Pass `dimensions` in outermost-to-innermost order and choose one or more `measures`.\n3. Use a row's `path` as `parent_path` to load its next nested level.\n\nThe nestable dimensions include title, ASIN, author, series, country, platform, date, account when Shared Access applies, and journal_event. Journal Events contain a Tooltip heading and Description, are counted by `journal_events`, and use Country `Other` because they have no marketplace. The endpoint supports date and entity filters, search, sorting, Relative date ranges such as `today` are resolved by the server in the account timezone; the response's `date_context` reports the authoritative current date and resolved range. pagination (up to 200 grouped rows per page), and CSV export via `export_mode` (up to 50,000 rows). Authenticated schema responses include account-specific custom book formats and their units/royalties measure keys, plus built-in and custom platform metadata for exact filters. Monetary values use the account's preferred currency unless `currency` overrides it. Shared Access accounts may be selected by alias or email; MCP requests with multiple accounts return `account_selection_required` until `selected_accounts` is supplied. Validation errors return HTTP 400 with a human-readable message.", "summary": "Query the Power Table", "parameters": [{"in": "query", "name": "account_id", "schema": {"type": "string"}, "description": "Account UUID associated with the API key.", "required": true}, {"in": "query", "name": "api_key", "schema": {"type": "string"}, "description": "Your unique API key.", "required": true}, {"in": "query", "name": "currency", "schema": {"type": "string", "enum": ["AED", "ARS", "AUD", "BDT", "BOB", "BRL", "CAD", "CHF", "CLP", "CNY", "COP", "CRC", "CZK", "DKK", "DZD", "EGP", "EUR", "GBP", "GTQ", "HKD", "HNL", "HUF", "IDR", "ILS", "INR", "ISK", "JPY", "KES", "KRW", "MOP", "MXN", "MYR", "NGN", "NIO", "NOK", "NZD", "PEN", "PHP", "PKR", "PLN", "PYG", "QAR", "RON", "RUB", "SAR", "SEK", "SGD", "STN", "THB", "TRY", "TWD", "UAH", "USD", "UYU", "VEF", "VND", "ZAR"], "pattern": "^[A-Z]{3}$"}, "description": "Optional three-letter currency code. Defaults to the account's preferred currency. Every supported currency is listed in the values below.", "examples": {"USDollars": {"value": "USD", "summary": "US dollars"}}}, {"in": "query", "name": "date_range", "schema": {"type": "string", "enum": ["last_30_days", "last_7_days", "last_90_days", "last_month", "last_week", "last_year", "this_month", "this_week", "this_year", "today", "yesterday"]}, "description": "Server-resolved relative range using the account's current date and timezone. Do not combine it with start_date or end_date.", "examples": {"TodayInTheAccountTimezone": {"value": "today", "summary": "Today in the account timezone"}}}, {"in": "query", "name": "dimensions", "schema": {"type": "array", "items": {"type": "string", "enum": ["account", "asin", "attribution_ad_group", "attribution_campaign", "attribution_campaign_ad_group", "author", "book_format", "book_tag", "date", "facebook_ad", "facebook_ad_account", "facebook_ad_group", "facebook_ad_id", "facebook_campaign", "journal_event", "marketplace", "month", "platform", "published_date", "quarter", "series", "title", "year", "year_month"]}}, "description": "Fields that define the nested rows, ordered outermost first. Defaults to `title`. Pass a comma-separated list, repeat the parameter, or use a JSON array in a POST body. Use `schema_only=1` to retrieve the account-specific catalog.", "explode": false, "style": "form", "examples": {"BooksByCountry": {"value": ["title", "marketplace"], "summary": "Nest Country rows beneath each Book Title."}, "AuthorsByMonth": {"value": ["author", "year_month"], "summary": "Nest Month and Year rows beneath each Author."}}}, {"in": "query", "name": "end_date", "schema": {"type": "string", "format": "date"}, "description": "Inclusive end date in YYYY-MM-DD format. Defaults to tomorrow.", "examples": {"EndOfJuly": {"value": "2026-07-31", "summary": "End of July"}}}, {"in": "query", "name": "include_free_units", "schema": {"type": "boolean", "default": true}, "description": "Whether Sell-Through includes free ebook units. Borrows remain excluded."}, {"in": "query", "name": "measures", "schema": {"type": "array", "items": {"type": "string", "enum": ["acos", "ad_clicks", "ad_conversion_rate", "ad_impressions", "ad_kenp_reads", "ad_orders", "all_stars_bonus", "amazon_ad_clicks", "amazon_ad_impressions", "amazon_ad_kenp_reads", "amazon_attribution_add_to_cart_clicks", "amazon_attribution_book_royalties", "amazon_attribution_borrows", "amazon_attribution_conversion_rate", "amazon_attribution_cost_per_sale", "amazon_attribution_detail_page_view_clicks", "amazon_attribution_kenp_reads", "amazon_attribution_net_sales", "amazon_attribution_orders", "amazon_attribution_read_royalties", "amazon_attribution_roas", "amazon_attribution_total_royalties", "amazon_attribution_total_units_sold", "amazon_cpc", "amazon_cpm", "amazon_ctr", "amz_spending", "audiobooks", "audiobooks_royalty", "bookbub_ad_clicks", "bookbub_ad_impressions", "bookbub_cpc", "bookbub_cpm", "bookbub_ctr", "bookbub_spending", "bsr", "cost_per_ad_order", "cpc", "cpm", "ctr", "ebooks_free", "ebooks_paid", "ebooks_paid_royalty", "estimated_ad_kenp_royalties", "expanded_distribution", "expanded_distribution_royalty", "external_expenses", "facebook_ad_clicks", "facebook_ad_impressions", "facebook_cpc", "facebook_cpm", "facebook_ctr", "fb_spending", "full_reads", "gross_royalties", "hardcovers", "hardcovers_royalty", "inorganic_orders_percentage", "journal_events", "net_royalties", "number_in_series", "other_royalty", "paperbacks", "paperbacks_royalty", "read_through", "reads", "reads_royalty", "roas", "roi", "royalties_per_reader", "royalty_per_unit", "rpr_contribution", "sell_through", "shared_amazon_attributed_read_royalties", "shared_amazon_attributed_sales", "shared_total_amazon_attributed_sales", "spending", "tacos", "total_ad_sales", "total_paid_units"]}}, "description": "Numbers to calculate for every row. Defaults to `total_paid_units`, `gross_royalties`, `spending`, and `net_royalties`. Multiple values may be comma-separated, repeated, or supplied as a JSON array in a POST body.", "explode": false, "style": "form", "examples": {"RoyaltiesAndUnits": {"value": ["gross_royalties", "total_paid_units", "net_royalties"], "summary": "Core sales performance."}, "AdvertisingEfficiency": {"value": ["spending", "total_ad_sales", "acos", "tacos", "roi"], "summary": "Spend, attributed sales, and efficiency."}, "KindleUnlimited": {"value": ["reads", "full_reads", "reads_royalty"], "summary": "KENP reads, estimated borrows, and KENP royalties."}}}, {"in": "query", "name": "page", "schema": {"type": "integer", "minimum": 1, "default": 1}, "description": "One-based result page."}, {"in": "query", "name": "page_size", "schema": {"type": "integer", "minimum": 1, "maximum": 200, "default": 25}, "description": "Grouped rows per page. Minimum 1; maximum 200."}, {"in": "query", "name": "parent_path", "schema": {"type": "string"}, "description": "Loads the next nested level beneath an existing row. Copy the row's `path` array from the previous response and JSON-encode it. Its dimensions must be the leading dimensions from the request.", "examples": {"OpenOneBook": {"value": "[{\"dimension\":\"title\",\"key\":\"the-example-book\"}]", "summary": "Load the next dimension beneath a Book Title row."}, "OpenOneCountryWithinABook": {"value": "[{\"dimension\":\"title\",\"key\":\"the-example-book\"},{\"dimension\":\"marketplace\",\"key\":\"Amazon.com\"}]", "summary": "Continue through a title \u2192 country hierarchy."}}}, {"in": "query", "name": "schema_only", "schema": {"type": "boolean"}, "description": "Set to true to return the available dimensions, measures, presets, entitlements, and limits without running a report.", "examples": {"DiscoverFields": {"value": true, "summary": "Discover fields"}}}, {"in": "query", "name": "selected_accounts", "schema": {"type": "array", "items": {"type": "string"}}, "description": "For connection-scoped Shared Access, select exact account aliases or emails returned in `account_scope`. Use `all` by itself to include every available account.", "examples": {"AllAvailableAccounts": {"value": ["all"], "summary": "All available accounts"}, "SpecificAccounts": {"value": ["Main Pen Name", "shared-author@example.com"], "summary": "Specific accounts"}}}, {"in": "query", "name": "selected_authors", "schema": {"type": "array", "items": {"type": "string"}}, "description": "Only include these exact author or pen names. Values are account-specific and match the names stored in the authenticated account.", "examples": {"OnePenName": {"value": ["A. N. Author"], "summary": "One pen name"}}}, {"in": "query", "name": "selected_book_series", "schema": {"type": "array", "items": {"type": "string"}}, "description": "Only include these exact series names. Values are account-specific and match the series stored in the authenticated account's Bookshelf.", "examples": {"OneSeries": {"value": ["The Example Series"], "summary": "One series"}}}, {"in": "query", "name": "selected_book_tags", "schema": {"type": "array", "items": {"type": "string"}}, "description": "Only include books with these account-specific tags. Use `tag_operation` to choose OR or AND matching.", "examples": {"LaunchTitles": {"value": ["launch", "priority"], "summary": "Launch titles"}}}, {"in": "query", "name": "selected_formats", "schema": {"type": "array", "items": {"type": "string", "enum": ["Audiobook", "EBook", "Hardcover", "KENP Reads", "Other", "Paperback"]}}, "description": "Only include these book formats. Every accepted format is listed below.", "explode": false, "style": "form", "examples": {"DigitalFormats": {"value": ["EBook", "Audiobook"], "summary": "Digital formats"}}}, {"in": "query", "name": "selected_marketplaces", "schema": {"type": "array", "items": {"type": "string", "enum": ["AE", "AU", "AUS", "BE", "BR", "CA", "CAN", "DE", "ES", "FR", "GB", "IE", "IN", "IT", "JP", "MX", "NL", "Other", "PL", "SA", "SE", "UK", "US", "USA"]}}, "description": "Country codes to include. `UK` and `GB` are equivalent. Use `Other` for non-Amazon or otherwise unassigned country data. Available values: `US` (United States), `UK` (United Kingdom), `GB` (United Kingdom), `DE` (Germany), `FR` (France), `ES` (Spain), `IT` (Italy), `NL` (Netherlands), `JP` (Japan), `IN` (India), `CA` (Canada), `BR` (Brazil), `MX` (Mexico), `BE` (Belgium), `IE` (Ireland), `AU` (Australia), `AE` (United Arab Emirates), `SA` (Saudi Arabia), `SE` (Sweden), `PL` (Poland), `USA` (United States), `AUS` (Australia), `CAN` (Canada), `Other` (Other or non-Amazon country).", "explode": false, "style": "form", "examples": {"USAndUK": {"value": ["US", "UK"], "summary": "US and UK"}, "GBAliasAndOther": {"value": ["GB", "Other"], "summary": "GB alias and other"}}}, {"in": "query", "name": "selected_platforms", "schema": {"type": "array", "items": {"type": "string"}}, "description": "Only include these publishing or advertising platforms. Built-in options: `ACX`, `Amazon`, `Apple Books`, `Authors Republic`, `Barnes & Noble Press`, `BookMundo`, `BookBub Ads`, `Draft2Digital`, `Facebook`, `Google Books`, `Gumroad`, `IngramSpark`, `Kobo Writing Life`, `Lemon Squeezy`, `Payhip`, `PayPal`, `PublishDrive`, `SamCart`, `Fourthwall`, `Squarespace`, `SquareUp`, `Shopify`, `Stripe`, `Spotify for Authors`, `Tolino Media`, `ThriveCart`, `Voices by INaudio`, `WooCommerce`, `Wix`, `Other`. Exact custom platform names configured on the authenticated account are also accepted.", "examples": {"AmazonAndDirectSales": {"value": ["Amazon", "Shopify"], "summary": "Amazon and direct sales"}}}, {"in": "query", "name": "selected_titles", "schema": {"type": "array", "items": {"type": "string"}}, "description": "Only include these exact book titles. Values are account-specific: use titles from the authenticated account's Publisher Champ Bookshelf.", "examples": {"TwoBooks": {"value": ["The Example Book", "The Sequel"], "summary": "Two books"}}}, {"in": "query", "name": "sort_by", "schema": {"type": "string"}, "description": "A requested measure, the current row dimension, `label`, or `record_count`. For example, use `gross_royalties` when it is included in `measures`.", "examples": {"HighestRoyalties": {"value": "gross_royalties", "summary": "Highest royalties"}, "AlphabeticalRows": {"value": "label", "summary": "Alphabetical rows"}}}, {"in": "query", "name": "sort_direction", "schema": {"type": "string", "enum": ["asc", "desc"]}, "description": "Sort direction. Measures normally default to descending and labels to ascending."}, {"in": "query", "name": "start_date", "schema": {"type": "string", "format": "date"}, "description": "Inclusive start date in YYYY-MM-DD format. Defaults to the first day of the current month.", "examples": {"StartOfJuly": {"value": "2026-07-01", "summary": "Start of July"}}}, {"in": "query", "name": "tag_operation", "schema": {"type": "string", "enum": ["AND", "OR"], "default": "OR"}, "description": "How multiple `selected_book_tags` are matched."}], "tags": ["Power Table"], "responses": {"200": {"content": {"application/json": {"schema": {"type": "object", "additionalProperties": {}}, "examples": {"GroupedReport": {"value": {"version": 3, "rows": [{"id": "0:title:the-example-book", "key": "the-example-book", "label": "The Example Book", "path": [{"dimension": "title", "key": "the-example-book"}], "dimension_values": {"title": {"key": "the-example-book", "label": "The Example Book"}}, "values": {"gross_royalties": 1842.73, "total_paid_units": 612, "net_royalties": 1497.22}, "record_count": 38, "child_count": 4, "has_children": true}], "recordsTotal": 1, "recordsFiltered": 1, "page": 1, "page_size": 25, "total_pages": 1, "current_dimension": "title", "current_dimensions": ["title"], "next_dimension": null, "next_dimensions": [], "parent_path": [], "totals": {"gross_royalties": 1842.73, "total_paid_units": 612, "net_royalties": 1497.22}, "currency": "USD", "schema_version": 6, "date_range": {"start_date": "2026-07-01", "end_date": "2026-07-30"}, "date_context": {"current_date": "2026-07-30", "timezone": "Europe/London", "requested_range": "this_month", "resolved_start_date": "2026-07-01", "resolved_end_date": "2026-07-30"}}, "summary": "Grouped report"}, "SchemaDiscovery": {"value": {"schema": {"version": 11, "dimensions": [{"key": "title", "label": "Book Title", "type": "string"}, {"key": "author", "label": "Author", "type": "string"}], "measures": [{"key": "gross_royalties", "label": "Total Gross Royalties", "type": "money"}, {"key": "total_paid_units", "label": "Total Paid Units", "type": "integer"}], "limits": {"max_dimensions": 8, "max_page_size": 200}}, "schema_version": 6}, "summary": "Schema discovery"}}}}, "description": "Grouped Power Table result, schema catalog, or account-selection prompt."}, "400": {"content": {"application/json": {"schema": {"type": "object", "additionalProperties": {}}, "examples": {"ValidationError": {"value": {"error": "Invalid api_key format"}, "summary": "Validation error"}}}}, "description": "Validation error"}, "401": {"content": {"application/json": {"schema": {"type": "object", "additionalProperties": {}}, "examples": {"AuthenticationError": {"value": {"error": "api_key is invalid"}, "summary": "Authentication error"}}}}, "description": "Authentication error"}, "403": {"content": {"application/json": {"schema": {"type": "object", "additionalProperties": {}}, "examples": {"SubscriptionError": {"value": {"error": "User subscription is not valid (you need an active subscription to access the API). Login and update your subscription to regain API access."}, "summary": "Subscription error"}}}}, "description": "Subscription or access error"}, "429": {"content": {"application/json": {"schema": {"type": "object", "additionalProperties": {}}, "examples": {"RateLimitExceeded": {"value": {"error": "Rate limit exceeded. Maximum 20 requests per minute per API key, with at least 3 seconds between requests.", "limit": "20 requests per minute per API key; maximum 1 request every 3 seconds"}, "summary": "Rate limit exceeded"}}}}, "description": "Rate limit exceeded"}}}}, "/api/v1/platformSyncStatusAPI/": {"get": {"operationId": "platformSyncStatusAPI_retrieve", "description": "Returns synchronization status for every automatic platform integration supported by Publisher Champ for the requested account.\n\nFull URL: `https://www.publisherchamp.com/api/v1/platformSyncStatusAPI/`\n\nPass the API key owner's `account_id`, or an `account_id` returned by `listAccountsAPI` that the API key is authorized to access. The selector is used only for authorization and is not echoed in the response. The endpoint never returns account UUIDs, email addresses, advertising entity IDs, cookies, access tokens, refresh tokens, consumer secrets, or other credentials or account identifiers.\n\nOnly enabled integrations that have synchronized at least once are returned. Platforms that have never synchronized, are disabled, or have never been connected are omitted. A previously synchronized platform that is currently out of sync remains in the response with `synced: false` and its last successful sync time. Amazon Ads and Facebook Ads are each aggregated into one platform row when multiple advertising connections exist.\n\n**Included platform IDs**\n\n- Publishing: `amazon_kdp`, `acx`, `d2d`, `bnn`, `fav`, `ingram`, `kobo`, `publishdrive`, `spotify`, `google_books`, `apple_books`, `bookmundo`, `ar`, `tolino`, `bookfunnel`\n- Advertising: `amazon_ads`, `facebook_ads`, `bookbub`\n- Storefront: `shopify`, `woocommerce`, `thrivecart`, `fourthwall`, `squarespace`, `squareup`\n\nEach platform row contains only `platform_id`, `platform_name`, `synced`, and `last_sync`. `last_sync` is an ISO 8601 datetime when available, otherwise `N/A`.\n\n**cURL example**\n\n```bash\ncurl \"https://www.publisherchamp.com/api/v1/platformSyncStatusAPI/?api_key=<API_KEY>&account_id=<ACCOUNT_UUID>\"\n```\n\n**Python example**\n\n```python\nimport requests\n\nresponse = requests.get(\n    \"https://www.publisherchamp.com/api/v1/platformSyncStatusAPI/\",\n    params={\"api_key\": \"<API_KEY>\", \"account_id\": \"<ACCOUNT_UUID>\"},\n)\nresponse.raise_for_status()\nplatforms = response.json()[\"platforms\"]\n```", "summary": "Get platform synchronization status", "parameters": [{"in": "query", "name": "account_id", "schema": {"type": "string"}, "description": "Account UUID associated with the API key.", "required": true}, {"in": "query", "name": "api_key", "schema": {"type": "string"}, "description": "Your unique API key.", "required": true}], "tags": ["Accounts"], "responses": {"200": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/PlatformSyncStatusResponse"}, "examples": {"ExampleResponse": {"value": {"platforms": [{"platform_id": "amazon_kdp", "platform_name": "Amazon KDP", "synced": true, "last_sync": "2026-08-02T14:25:31+00:00"}, {"platform_id": "amazon_ads", "platform_name": "Amazon Ads", "synced": true, "last_sync": "2026-08-02T13:50:12+00:00"}, {"platform_id": "facebook_ads", "platform_name": "Facebook Ads", "synced": false, "last_sync": "N/A"}]}, "summary": "Example response"}}}}, "description": "Successful response"}, "400": {"content": {"application/json": {"schema": {"type": "object", "additionalProperties": {}}, "examples": {"ValidationError": {"value": {"error": "Invalid api_key format"}, "summary": "Validation error"}}}}, "description": "Validation error"}, "401": {"content": {"application/json": {"schema": {"type": "object", "additionalProperties": {}}, "examples": {"AuthenticationError": {"value": {"error": "api_key is invalid"}, "summary": "Authentication error"}}}}, "description": "Authentication error"}, "403": {"content": {"application/json": {"schema": {"type": "object", "additionalProperties": {}}, "examples": {"SubscriptionError": {"value": {"error": "User subscription is not valid (you need an active subscription to access the API). Login and update your subscription to regain API access."}, "summary": "Subscription error"}}}}, "description": "Subscription or access error"}, "429": {"content": {"application/json": {"schema": {"type": "object", "additionalProperties": {}}, "examples": {"RateLimitExceeded": {"value": {"error": "Rate limit exceeded. Maximum 20 requests per minute per API key, with at least 3 seconds between requests.", "limit": "20 requests per minute per API key; maximum 1 request every 3 seconds"}, "summary": "Rate limit exceeded"}}}}, "description": "Rate limit exceeded"}}}}, "/api/v1/seriesListAPI/": {"get": {"operationId": "seriesListAPI_retrieve", "description": "Returns the book series available to the requested account.\n\nFull URL: `https://www.publisherchamp.com/api/v1/seriesListAPI/`\n\nUse the returned `series` value as the `series` parameter for `seriesStatsAPI`.", "summary": "List book series available to an API key", "parameters": [{"in": "query", "name": "account_id", "schema": {"type": "string"}, "description": "Account UUID associated with the API key.", "required": true}, {"in": "query", "name": "api_key", "schema": {"type": "string"}, "description": "Your unique API key.", "required": true}, {"in": "query", "name": "length", "schema": {"type": "integer"}, "description": "Rows per page. Defaults to 100 and cannot exceed 100."}, {"in": "query", "name": "page", "schema": {"type": "integer"}, "description": "Page number. Defaults to 1."}, {"in": "query", "name": "search_q", "schema": {"type": "string"}, "description": "Optional substring search applied to series names."}], "tags": ["Catalog"], "responses": {"200": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/SeriesListResponse"}, "examples": {"ExampleResponse": {"value": {"total_results": 2, "page": 1, "length": 100, "total_pages": 1, "table_data": [{"series": "Example Fantasy Series", "books_count": 3, "asins": ["B000000001", "B000000002", "B000000003"]}, {"series": "Example Mystery Series", "books_count": 2, "asins": ["B000000101", "B000000102"]}]}, "summary": "Example response"}}}}, "description": "Successful response"}, "400": {"content": {"application/json": {"schema": {"type": "object", "additionalProperties": {}}, "examples": {"ValidationError": {"value": {"error": "Invalid api_key format"}, "summary": "Validation error"}}}}, "description": "Validation error"}, "401": {"content": {"application/json": {"schema": {"type": "object", "additionalProperties": {}}, "examples": {"AuthenticationError": {"value": {"error": "api_key is invalid"}, "summary": "Authentication error"}}}}, "description": "Authentication error"}, "403": {"content": {"application/json": {"schema": {"type": "object", "additionalProperties": {}}, "examples": {"SubscriptionError": {"value": {"error": "User subscription is not valid (you need an active subscription to access the API). Login and update your subscription to regain API access."}, "summary": "Subscription error"}}}}, "description": "Subscription or access error"}, "429": {"content": {"application/json": {"schema": {"type": "object", "additionalProperties": {}}, "examples": {"RateLimitExceeded": {"value": {"error": "Rate limit exceeded. Maximum 20 requests per minute per API key, with at least 3 seconds between requests.", "limit": "20 requests per minute per API key; maximum 1 request every 3 seconds"}, "summary": "Rate limit exceeded"}}}}, "description": "Rate limit exceeded"}}}}, "/api/v1/seriesStatsAPI/": {"get": {"operationId": "seriesStatsAPI_retrieve", "description": "Returns sell-through and read-through progression for one book series.\n\nFull URL: `https://www.publisherchamp.com/api/v1/seriesStatsAPI/`\n\nThe response is ordered by `number_in_series`. For book 1, sell-through and read-through percentages are `null`; from book 2 onward:\n- `sell_through_percent` compares units sold for this book to the previous book.\n- `cumulative_sell_through_percent` compares units sold for this book to book 1.\n- `read_through_percent` compares estimated full reads for this book to the previous book.\n- `cumulative_read_through_percent` compares estimated full reads for this book to book 1.", "summary": "List series performance stats for an account", "parameters": [{"in": "query", "name": "account_id", "schema": {"type": "string"}, "description": "Account UUID associated with the API key.", "required": true}, {"in": "query", "name": "api_key", "schema": {"type": "string"}, "description": "Your unique API key.", "required": true}, {"in": "query", "name": "book_formats", "schema": {"type": "string"}, "description": "Comma-separated built-in or user-created bookshelf formats. Defaults to every sales-capable format on the account."}, {"in": "query", "name": "countries", "schema": {"type": "string"}, "description": "Optional comma-separated marketplace/country filter. Use country codes like US, UK (or GB), DE, FR, ES, IT, NL, JP, IN, CA, BR, MX, AU, BE, IE, AE, SA, SE, PL, or special values Facebook, Other. Marketplace names (for example Amazon.com, Amazon.co.uk) are also accepted and normalized. Empty value (countries=) means all marketplaces."}, {"in": "query", "name": "end_date", "schema": {"type": "string", "format": "date"}, "description": "End date (YYYY-MM-DD). Must be within 365 days of start_date.", "required": true}, {"in": "query", "name": "platforms", "schema": {"type": "string"}, "description": "Optional comma-separated publishing platforms. Defaults to the account's enabled platforms. Available built-in values: ACX, Amazon, Apple Books, Authors Republic, Barnes & Noble Press, BookMundo, BookBub Ads, Draft2Digital, Facebook, Google Books, Gumroad, IngramSpark, Kobo Writing Life, Lemon Squeezy, Payhip, PayPal, PublishDrive, SamCart, Fourthwall, Squarespace, SquareUp, Shopify, Stripe, Spotify for Authors, Tolino Media, ThriveCart, Voices by INaudio, WooCommerce, Wix, Other. Custom platforms configured on the account are also accepted."}, {"in": "query", "name": "sale_types", "schema": {"type": "string"}, "description": "Comma-separated values. Available values: paid, free. Defaults to paid,free."}, {"in": "query", "name": "series", "schema": {"type": "string"}, "description": "Series name returned by seriesListAPI.", "required": true}, {"in": "query", "name": "start_date", "schema": {"type": "string", "format": "date"}, "description": "Start date (YYYY-MM-DD). The requested date range cannot exceed 365 days.", "required": true}], "tags": ["Analytics"], "responses": {"200": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/SeriesStatsResponse"}, "examples": {"ExampleResponse": {"value": {"series": "Example Fantasy Series", "start_date": "2026-01-01", "end_date": "2026-05-29", "currency": "USD", "estimated_tacos": 184.77, "sell_thru_revenue": 5.86, "read_thru_revenue": 1.42, "table_data": [{"number_in_series": 1, "asins": ["B000000001"], "titles": ["Example Fantasy Book 1"], "total_ebooks_sold": 1000, "total_paid_ebooks_sold": 850, "total_free_ebooks_sold": 150, "total_reads": 250000, "full_reads": 500, "kenpc": 500.0, "book_royalties": 2400.0, "read_royalties": 710.0, "book_price": 2.4, "sell_through_percent": null, "cumulative_sell_through_percent": null, "read_through_percent": null, "cumulative_read_through_percent": null}, {"number_in_series": 2, "asins": ["B000000002"], "titles": ["Example Fantasy Book 2"], "total_ebooks_sold": 650, "total_paid_ebooks_sold": 620, "total_free_ebooks_sold": 30, "total_reads": 180000, "full_reads": 360, "kenpc": 500.0, "book_royalties": 1900.0, "read_royalties": 510.0, "book_price": 2.92, "sell_through_percent": 65.0, "cumulative_sell_through_percent": 65.0, "read_through_percent": 72.0, "cumulative_read_through_percent": 72.0}]}, "summary": "Example response"}}}}, "description": "Successful response"}, "400": {"content": {"application/json": {"schema": {"type": "object", "additionalProperties": {}}, "examples": {"ValidationError": {"value": {"error": "Invalid api_key format"}, "summary": "Validation error"}}}}, "description": "Validation error"}, "401": {"content": {"application/json": {"schema": {"type": "object", "additionalProperties": {}}, "examples": {"AuthenticationError": {"value": {"error": "api_key is invalid"}, "summary": "Authentication error"}}}}, "description": "Authentication error"}, "403": {"content": {"application/json": {"schema": {"type": "object", "additionalProperties": {}}, "examples": {"SubscriptionError": {"value": {"error": "User subscription is not valid (you need an active subscription to access the API). Login and update your subscription to regain API access."}, "summary": "Subscription error"}}}}, "description": "Subscription or access error"}, "429": {"content": {"application/json": {"schema": {"type": "object", "additionalProperties": {}}, "examples": {"RateLimitExceeded": {"value": {"error": "Rate limit exceeded. Maximum 20 requests per minute per API key, with at least 3 seconds between requests.", "limit": "20 requests per minute per API key; maximum 1 request every 3 seconds"}, "summary": "Rate limit exceeded"}}}}, "description": "Rate limit exceeded"}}}}}, "components": {"schemas": {"AdsMonitoringResponse": {"type": "object", "properties": {"table_data": {"type": "object", "additionalProperties": {}, "description": "Date-keyed breakdown when breakdown is daily/monthly; otherwise ad performance keyed by ASIN or grouped title reference."}, "start_date": {"type": "string", "format": "date", "description": "The start date the returned data covers."}, "end_date": {"type": "string", "format": "date", "description": "The end date the returned data covers."}, "breakdown": {"type": "string", "description": "Returned breakdown granularity: daily or monthly."}, "granularity": {"type": "string", "description": "Effective data granularity: daily or monthly."}}, "required": ["end_date", "start_date", "table_data"]}, "AmazonAttributionAdTagRequest": {"type": "object", "properties": {"api_key": {"type": "string", "description": "Publisher Champ API key."}, "account_id": {"type": "string", "description": "Publisher Champ account UUID."}, "search_q": {"type": "string", "description": "Optional substring search applied to attribution_id."}, "page": {"type": "integer", "minimum": 1, "description": "Page number to return. Defaults to 1."}, "length": {"type": "integer", "maximum": 100, "minimum": 1, "description": "Rows per page. Defaults to 100 and cannot exceed 100."}}, "required": ["account_id", "api_key"]}, "AmazonAttributionAdTagRow": {"type": "object", "properties": {"attribution_id": {"type": "string", "description": "Amazon Attribution id."}, "tag": {"type": "string", "description": "Amazon Attribution ad tag."}}, "required": ["attribution_id", "tag"]}, "AmazonAttributionAdTagsResponse": {"type": "object", "properties": {"total_results": {"type": "integer", "description": "Total rows matching the request."}, "page": {"type": "integer", "description": "Returned page number."}, "length": {"type": "integer", "description": "Rows requested per page."}, "total_pages": {"type": "integer", "description": "Total available pages for the requested length."}, "table_data": {"type": "array", "items": {"$ref": "#/components/schemas/AmazonAttributionAdTagRow"}, "description": "Paginated attribution_id to tag rows."}}, "required": ["length", "page", "table_data", "total_pages", "total_results"]}, "AuthorStatsResponse": {"type": "object", "properties": {"table_data": {"type": "object", "additionalProperties": {}, "description": "Date-keyed breakdown when breakdown is daily/monthly; otherwise author breakdown keyed by author name."}, "start_date": {"type": "string", "format": "date", "description": "The start date the returned data covers."}, "end_date": {"type": "string", "format": "date", "description": "The end date the returned data covers."}, "breakdown": {"type": "string", "description": "Returned breakdown granularity: daily or monthly."}, "granularity": {"type": "string", "description": "Effective data granularity: daily or monthly."}}, "required": ["end_date", "start_date", "table_data"]}, "BookStatsResponse": {"type": "object", "properties": {"table_data": {"type": "object", "additionalProperties": {}, "description": "Date-keyed breakdown when breakdown is daily/monthly; otherwise book-level data rows."}, "start_date": {"type": "string", "format": "date", "description": "The start date the returned data covers."}, "end_date": {"type": "string", "format": "date", "description": "The end date the returned data covers."}, "breakdown": {"type": "string", "description": "Returned breakdown granularity: daily or monthly."}, "granularity": {"type": "string", "description": "Effective data granularity: daily or monthly."}}, "required": ["end_date", "start_date", "table_data"]}, "CountryStatsCountry": {"type": "object", "properties": {"original": {"type": "string", "description": "Total earnings in the marketplace's original currency. Can be '-' when not meaningful."}, "converted": {"type": "number", "format": "double", "description": "Total earnings converted to the response currency."}, "original_currency": {"type": "string", "description": "Original currency for the marketplace or country."}, "converted_currency": {"type": "string", "description": "Currency used for converted values in the response."}, "original_spend": {"type": "string", "description": "Total spend in the original marketplace currency. Can be '-' when not meaningful."}, "converted_spend": {"type": "number", "format": "double", "description": "Total spend converted to the response currency."}, "converted_amz_spend": {"type": "number", "format": "double", "description": "Amazon Ads spend converted to the response currency."}, "converted_ad_sales": {"type": "number", "format": "double", "description": "Ad-attributed sales converted to the response currency."}}, "required": ["converted", "converted_ad_sales", "converted_amz_spend", "converted_currency", "converted_spend", "original", "original_currency", "original_spend"]}, "CountryStatsResponse": {"type": "object", "properties": {"table_data": {"type": "object", "additionalProperties": {}, "description": "Date-keyed breakdown when breakdown is daily/monthly."}, "countries": {"type": "object", "additionalProperties": {"$ref": "#/components/schemas/CountryStatsCountry"}, "description": "Country or marketplace breakdown keyed by country name."}, "global_earnings": {"type": "number", "format": "double", "description": "Total earnings across all included countries."}, "global_spend": {"type": "number", "format": "double", "description": "Total spend across all included countries."}, "global_amz_spend": {"type": "number", "format": "double", "description": "Total Amazon Ads spend across all included countries."}, "global_ad_sales": {"type": "number", "format": "double", "description": "Total ad-attributed sales across all included countries."}, "converted_currency": {"type": "string", "description": "Currency used for converted values in the response."}, "start_date": {"type": "string", "format": "date", "description": "The start date the returned data covers."}, "end_date": {"type": "string", "format": "date", "description": "The end date the returned data covers."}, "breakdown": {"type": "string", "description": "Returned breakdown granularity: daily or monthly."}, "granularity": {"type": "string", "description": "Effective data granularity: daily or monthly."}}, "required": ["converted_currency", "countries", "end_date", "global_ad_sales", "global_amz_spend", "global_earnings", "global_spend", "start_date"]}, "JournalEventRow": {"type": "object", "properties": {"date": {"type": "string", "format": "date", "description": "Journal event date in YYYY-MM-DD format."}, "tooltip": {"type": "string", "nullable": true, "description": "Short journal event label."}, "description": {"type": "string", "nullable": true, "description": "Longer journal event notes."}, "annotate_on_graphs": {"type": "boolean", "description": "Whether this event is shown as an annotation on graphs."}, "annotation_color": {"type": "string", "description": "Graph annotation color."}, "title": {"type": "string", "nullable": true, "description": "Related book title, when available."}, "asin": {"type": "string", "nullable": true, "description": "Related ASIN or platform-specific title identifier, when available."}}, "required": ["annotate_on_graphs", "annotation_color", "asin", "date", "description", "title", "tooltip"]}, "JournalEventsResponse": {"type": "object", "properties": {"total_results": {"type": "integer", "description": "Number of journal events returned."}, "journal_events": {"type": "array", "items": {"$ref": "#/components/schemas/JournalEventRow"}, "description": "All journal events belonging to the requested account."}}, "required": ["journal_events", "total_results"]}, "ListAccountsItem": {"type": "object", "properties": {"account_id": {"type": "string", "description": "Account UUID."}, "user_email": {"type": "string", "description": "Email address of the account owner."}, "access_granted_at": {"type": "string", "nullable": true, "description": "When access was granted, if applicable."}, "access_type": {"type": "string", "description": "How this account is accessible to the API key owner."}, "external_user_id": {"type": "string", "description": "Optional external user ID stored with the access grant."}}, "required": ["access_granted_at", "access_type", "account_id", "user_email"]}, "ListAccountsResponse": {"type": "object", "properties": {"api_key": {"type": "string", "description": "The API key used for the request."}, "api_key_owner_email": {"type": "string", "nullable": true, "description": "Email address of the API key owner."}, "accounts": {"type": "array", "items": {"$ref": "#/components/schemas/ListAccountsItem"}, "description": "Accounts accessible to this API key."}}, "required": ["accounts", "api_key", "api_key_owner_email"]}, "PlatformSyncItem": {"type": "object", "properties": {"platform_id": {"type": "string", "description": "Stable machine-readable platform identifier."}, "platform_name": {"type": "string", "description": "Human-readable platform name."}, "synced": {"type": "boolean", "description": "Whether the platform is currently synchronized."}, "last_sync": {"type": "string", "description": "Most recent sync in ISO 8601 format, or N/A when no timestamp is available."}}, "required": ["last_sync", "platform_id", "platform_name", "synced"]}, "PlatformSyncStatusResponse": {"type": "object", "properties": {"platforms": {"type": "array", "items": {"$ref": "#/components/schemas/PlatformSyncItem"}, "description": "Enabled automatic integrations that have synchronized at least once."}}, "required": ["platforms"]}, "SeriesListResponse": {"type": "object", "properties": {"total_results": {"type": "integer", "description": "Total series matching the request."}, "page": {"type": "integer", "description": "Returned page number."}, "length": {"type": "integer", "description": "Rows requested per page."}, "total_pages": {"type": "integer", "description": "Total available pages for the requested length."}, "table_data": {"type": "array", "items": {"$ref": "#/components/schemas/SeriesListRow"}, "description": "Paginated list of accessible series."}}, "required": ["length", "page", "table_data", "total_pages", "total_results"]}, "SeriesListRow": {"type": "object", "properties": {"series": {"type": "string", "description": "Series name to pass to the series stats endpoint."}, "books_count": {"type": "integer", "description": "Number of accessible books assigned to the series."}, "asins": {"type": "array", "items": {"type": "string"}, "description": "Accessible ASINs assigned to the series."}}, "required": ["asins", "books_count", "series"]}, "SeriesStatsResponse": {"type": "object", "properties": {"series": {"type": "string", "description": "Requested series name."}, "start_date": {"type": "string", "format": "date", "description": "Start date used for the report."}, "end_date": {"type": "string", "format": "date", "description": "End date used for the report."}, "currency": {"type": "string", "description": "Currency used for royalties."}, "estimated_tacos": {"type": "number", "format": "double", "description": "Total series royalties divided by book 1 royalties, as a percentage."}, "sell_thru_revenue": {"type": "number", "format": "double", "description": "Estimated sell-through revenue metric used by the web series stats page."}, "read_thru_revenue": {"type": "number", "format": "double", "description": "Estimated read-through revenue metric used by the web series stats page."}, "table_data": {"type": "object", "additionalProperties": {}, "description": "Date-keyed breakdown when breakdown is daily/monthly; otherwise series progression rows by book number."}, "breakdown": {"type": "string", "description": "Returned breakdown granularity: daily or monthly."}, "granularity": {"type": "string", "description": "Effective data granularity: daily or monthly."}}, "required": ["currency", "end_date", "estimated_tacos", "read_thru_revenue", "sell_thru_revenue", "series", "start_date", "table_data"]}}}, "servers": [{"url": "https://www.publisherchamp.com", "description": "Publisher Champ production API"}], "tags": [{"name": "Power Table", "description": "Flexible, nestable publishing analytics."}, {"name": "Analytics", "description": "Ready-made sales, royalty, advertising, and performance reports."}, {"name": "Advertising", "description": "Amazon Ads and Amazon Attribution reporting."}, {"name": "Catalog", "description": "Series and title discovery."}, {"name": "Accounts", "description": "Discover accessible accounts and inspect their platform synchronization health."}, {"name": "Journal", "description": "Read dated journal events attached to an account."}]}