PopunderStore — Advertiser API v1 Documentation

Advertiser API v1

PopunderStore’s Advertiser API v1 allows you to programmatically access your campaign performance data, conversions and account balance. The API is designed for affiliates, agencies and in-house tools that need simple, privacy-friendly and structured data for reporting, optimisation and reconciliation — without exposing raw user logs or sensitive information.

Base URL: https://api.popunder.store/v1/

Format: JSON, UTF-8, HTTPS only

Authentication: X-API-Key header or ?api_key=...

1. Authentication 2. General Rules /stats.php /conversions.php /campaigns.php /balance.php Postback /v1/postback.php

1. Authentication (API key)

All advertiser endpoints (except postback.php) require an API key. The key is unique per advertiser and must be kept secret. Treat it like a password.

You can generate or reset your API key in the advertiser interface on the Statistics page, inside the “API Access” block.

The key can be passed either:

as an HTTP header: X-API-Key: YOUR_KEY_HERE, or
as a query parameter: ?api_key=YOUR_KEY_HERE.

// basic example using query parameter
GET https://api.popunder.store/v1/stats.php?api_key=YOUR_KEY

// basic example using header
GET /v1/stats.php
X-API-Key: YOUR_KEY

If the key is missing or invalid, the API responds with "status": "error" and one of the error codes: missing_api_key or invalid_api_key, together with HTTP status 400 or 401.

2. General Rules & Response Format

All responses are JSON objects with a top-level status field:
- "status": "ok" – request was successful.
- "status": "error" – something went wrong.
On errors, you also receive:
- error – machine-readable error code.
- message – human-readable description.

{
  "status": "error",
  "error": "invalid_date_range",
  "message": "date_from must be <= date_to"

}

All dates in parameters are in YYYY-MM-DD format (e.g. 2025-11-26).
All timestamps returned from the API are in server time (UTC by default, unless stated otherwise).
Monetary values are returned in USD by default, with up to 4 decimal places for precision.
When aggregating statistics, metrics are derived from internal statistics and conversion tables used by PopunderStore’s reporting engine.
The Advertiser API never returns end-user IP addresses, user agents or other personally identifiable information. All optimisation is done on the level of campaigns, site_id and source.
Rate-limits: standard usage for reporting / dashboards is allowed. If you plan to hit the API very frequently (e.g. automated bidding), please contact support so we can align on limits and best practices.

3. Campaign Statistics — `/v1/stats.php`

GET /v1/stats.php

Returns aggregated performance metrics for your traffic over a specified date range. The endpoint supports two aggregation modes:

Per day & campaign (default) – high-level overview.
Per day, campaign, site_id & source – to optimise specific placements and traffic sources.

Parameters

Parameter	Status	Type	Description
`api_key`	required	string	Your advertiser API key.
`date_from`	optional	date	Start of the reporting period in `YYYY-MM-DD` format. If omitted, defaults to 7 days before `date_to` (or today if `date_to` is also omitted).
`date_to`	optional	date	End of the reporting period. If omitted, defaults to today. `date_to` must be greater or equal to `date_from`.
`campaign_id`	optional	int	If provided, stats are returned only for this campaign.
`group_by`	optional	string	Aggregation mode: `campaign` (default) – per day & campaign, `site_source` – per day, campaign, `site_id` & `source`.

Example request (campaign-level)

GET https://api.popunder.store/v1/stats.php?api_key=YOUR_KEY&date_from=2025-11-20&date_to=2025-11-26

Example response (`group_by=campaign`)

{
  "status": "ok",
  "date_from": "2025-11-20",
  "date_to": "2025-11-26",
  "group_by": "campaign",
  "campaign_id": null,
  "count": 1,
  "totals": {
    "impressions": 3,
    "cost": 0.015,
    "revenue": 0,
    "conversions": 0,
    "ecpm": 5,
    "ecpa": 0,
    "cr": 0,
    "profit": -0.015
  },
  "data": [
    {
      "date": "2025-11-26",
      "campaign_id": 17,
      "campaign_name": "tier1 campaign",
      "impressions": "3",
      "cost": "0.0150",
      "revenue": "0.0000",
      "conversions": "0",
      "ecpm": "5.00000000",
      "ecpa": "0",
      "cr": "0.0000",
      "profit": "-0.0150"
    }
  ]
}

Example response (`group_by=site_source`)

{
  "status": "ok",
  "date_from": "2025-11-20",
  "date_to": "2025-11-26",
  "group_by": "site_source",
  "campaign_id": 17,
  "count": 2,
  "totals": {
    "impressions": 24000,
    "cost": 18.00,
    "revenue": 25.50,
    "conversions": 40,
    "ecpm": 0.75,
    "ecpa": 0.64,
    "cr": 0.0017,
    "profit": 7.50
  },
  "data": [
    {
      "date": "2025-11-26",
      "campaign_id": 17,
      "campaign_name": "tier1 campaign",
      "site_id": 10,
      "source": "main",
      "impressions": "15000",
      "cost": "12.0000",
      "revenue": "18.0000",
      "conversions": "30",
      "ecpm": "0.8000",
      "ecpa": "0.4000",
      "cr": "0.0020",
      "profit": "6.0000"
    },
    {
      "date": "2025-11-26",
      "campaign_id": 17,
      "campaign_name": "tier1 campaign",
      "site_id": 11,
      "source": "9234192",
      "impressions": "9000",
      "cost": "6.0000",
      "revenue": "7.5000",
      "conversions": "10",
      "ecpm": "0.6667",
      "ecpa": "0.7500",
      "cr": "0.0011",
      "profit": "1.5000"
    }
  ]
}

Metric definitions:

impressions – number of popunder impressions served.
cost – advertiser spend for these impressions (USD).
revenue – sum of conversion revenue recorded via postback (USD).
conversions – number of tracked conversions.
ecpm – effective CPM = cost / impressions * 1000.
ecpa – effective CPA = cost / conversions (if conversions > 0).
cr – conversion rate = conversions / impressions.
profit – revenue - cost. Negative value means you are currently in loss.

4. Conversions — `/v1/conversions.php`

GET /v1/conversions.php

Returns a list of individual conversions recorded via the advertiser’s postback, together with aggregated totals (number of conversions and total revenue). Each conversion is linked to the campaign and to the placement that generated it via site_id and source.

This endpoint is typically used for:

lead-level reconciliation against third-party trackers or CPA networks,
advanced analytics by subid, site_id and source,
debugging postback integration and validating revenue.

Parameters

Parameter	Status	Type	Description
`api_key`	required	string	Your advertiser API key.
`date_from`	optional	date	Start of the period by `conversions.created_at`. Defaults to 7 days ago.
`date_to`	optional	date	End of the period by `conversions.created_at`. Defaults to today.
`campaign_id`	optional	int	Filter conversions by campaign.
`clickid`	optional	string	Return conversions only for a specific `click_id`. This is mainly used for technical debugging and 1:1 matching with external trackers.
`limit`	optional	int	Number of rows to return (default 1000, max 10000).
`offset`	optional	int	Offset for pagination (default 0).

Example request

GET https://api.popunder.store/v1/conversions.php?api_key=YOUR_KEY&date_from=2025-11-20&date_to=2025-11-26

Example response

{
  "status": "ok",
  "date_from": "2025-11-20",
  "date_to": "2025-11-26",
  "campaign_id": null,
  "clickid": null,
  "count": 2,
  "totals": {
    "conversions": 2,
    "revenue": 4.70
  },
  "limit": 1000,
  "offset": 0,
  "data": [
    {
      "id": 101,
      "created_at": "2025-11-25 22:15:59",
      "click_id": "22d69d308430f3eaaa569df11e17fb36",
      "campaign_id": 18,
      "campaign_name": "Example Campaign",
      "site_id": 10,
      "source": "main",
      "revenue": 1.50,
      "currency": "USD",
      "external_id": "AFF-12345",
      "subid0": "US",
      "subid1": "GoogleAds",
      "subid2": null,
      "subid3": null,
      "subid4": null
    },
    {
      "id": 102,
      "created_at": "2025-11-25 22:20:10",
      "click_id": "98bd0f14322789aa7673547e92e87c10",
      "campaign_id": 18,
      "campaign_name": "Example Campaign",
      "site_id": 11,
      "source": "984936",
      "revenue": 3.20,
      "currency": "USD",
      "external_id": "AFF-12346",
      "subid0": "US",
      "subid1": "Native",
      "subid2": null,
      "subid3": null,
      "subid4": null
    }
  ]
}

Notes:

Fields site_id and source allow you to see exactly which placements and traffic sources generated each conversion.
Fields subid0–subid4 are stored exactly as they were received in the postback request. You can use them for tracker campaign ID, GEO, creative ID, etc.
The API does not expose internal publisher identifiers or raw log data. All sensitive routing details remain on PopunderStore’s side.

5. Campaigns — `/v1/campaigns.php`

GET /v1/campaigns.php

Returns a list of campaigns belonging to the authenticated advertiser, including main configuration fields and targeting settings. This endpoint is useful for:

synchronising campaign metadata with your tracker or CRM,
building custom interfaces on top of PopunderStore,
debugging bids, budgets and targeting.

Parameters

Parameter	Status	Type	Description
`api_key`	required	string	Your advertiser API key.
`campaign_id`	optional	int	Return only a single campaign with this ID.
`status`	optional	string	Filter by status: `active`, `paused`, `completed`, `rejected`.

Example response

{
  "status": "ok",
  "count": 2,
  "data": [
    {
      "id": 17,
      "name": "tier2 campaign",
      "status": "active",
      "daily_budget": 20,
      "total_budget": 200,
      "created_at": "2025-11-20 11:32:10",
      "bid": 3.0,
      "popunder_url": "https://example.com/?clickid={clickid}",
      "geo": ["US"],
      "device": ["desktop"],
      "os": ["Windows","Mac","Linux"],
      "browser": ["Chrome","Firefox","Safari"],
      "freq_cap": 3
    }
  ]
}

Notes:

Targeting fields (geo, device, os, browser) are arrays derived from the JSON settings field in the campaigns table.
popunder_url is the final target URL used for redirects. PopunderStore automatically appends clickid=... to this URL when sending traffic.

6. Balance — `/v1/balance.php`

GET /v1/balance.php

Returns the current account balance for the authenticated advertiser. The balance is calculated as:

Total deposits – sum of completed positive payments from the payments table.
Total spent – sum of stats.spend across all ads for this advertiser.

This endpoint is typically used to display the balance inside custom dashboards or to implement simple budget alerts on your side.

Parameters

Parameter	Status	Type	Description
`api_key`	required	string	Your advertiser API key.

Example response

{
  "status": "ok",
  "user_id": 42,
  "email": "advertiser@example.com",
  "currency": "USD",
  "total_deposit": 500.00,
  "total_spent": 320.53,
  "balance": 179.47,
  "generated_at": "2025-11-26 22:40:12"
}

Tip: If you build your own tools, you can periodically poll this endpoint and trigger internal notifications when balance drops below your desired threshold.

7. Postback — `/v1/postback.php`

GET /v1/postback.php

The postback endpoint is used by third-party tracking systems, CPA networks or your own back-end to notify PopunderStore about a conversion that happened after the click. Once the conversion is received and validated, PopunderStore:

creates a row in the conversions table,
links it to the original click via click_id,
includes the conversion in your stats and totals.

Base format

https://api.popunder.store/v1/postback.php?clickid={clickid}&revenue={revenue}

Parameters

Parameter	Status	Description
`clickid`	required	Unique click identifier. PopunderStore appends this value to your offer URL as `clickid=...`. You must store and pass the same value back on conversion.
`revenue`	optional	Conversion amount in USD. If you prefer, you may use `payout` or `cost` instead – the script will pick whichever is present and map it to internal `revenue`.
`currency`	optional	Currency code (default `USD`). At the moment used as an informational field; all calculations on our side are done in USD.
`txid` / `tid` / `transaction_id`	optional	External transaction ID or lead ID from your tracker / CRM / affiliate network. Stored in `conversions.external_id`.
`subid0`–`subid4`	optional	Free-form tracking fields (for example: country, traffic source, campaign ID, ad group, creative ID). They are stored in `conversions.subid0`–`subid4` and are visible through the `conversions.php` API.

Examples

// simplest example — fixed payout
https://api.popunder.store/v1/postback.php?clickid=test123&revenue=1.23

// Clickaine-style example with subids
https://api.popunder.store/v1/postback.php
  ?clickid={clickid}
  &revenue={payout}
  &subid0={country}
  &subid1={traffic_source}

Behaviour:

If the provided clickid is not found in traffic_logs, the endpoint responds with

1. Authentication (API key)

2. General Rules & Response Format

3. Campaign Statistics — /v1/stats.php

Parameters

Example request (campaign-level)

Example response (group_by=campaign)

Example response (group_by=site_source)

4. Conversions — /v1/conversions.php

Parameters

Example request

Example response

5. Campaigns — /v1/campaigns.php

Parameters

Example response

6. Balance — /v1/balance.php

Parameters

Example response

7. Postback — /v1/postback.php

Base format

Parameters

Examples

3. Campaign Statistics — `/v1/stats.php`

Example response (`group_by=campaign`)

Example response (`group_by=site_source`)

4. Conversions — `/v1/conversions.php`

5. Campaigns — `/v1/campaigns.php`

6. Balance — `/v1/balance.php`

7. Postback — `/v1/postback.php`