Technical specification
The contract behind AdPage Feed v1: endpoints, fields, the four rules a feed has to follow, and how to test it. For the developer who builds the feed.
Version 1.0 · stable · questions: support@adpage.io
This is the contract a feed has to meet to connect to AdPage without custom work on either side. It is written for the developer who builds the endpoints. What the feed is for, and how to connect it once it works, is on AdPage Feed (your own API).
AdPage pulls the data; you never send anything. The weekly revenue becomes the target of the Marketing Mix Model: the series your advertising budget has to explain. That is why the grain is an ISO week rather than a day or an order, and why totals are enough.
Transport and authentication
Protocol
HTTPS only. Redirects are not followed, so the base URL has to answer directly.
Method
GET
Authentication
One static secret in an HTTP header, on every request
Header name
Your choice. Authorization: Bearer <token> is recommended; a name of your own, such as Ocp-Apim-Subscription-Key on Azure API Management, works just as well.
Keys
Issue two, a primary and a secondary, both valid at the same time. That makes rotation possible without an interruption.
Revoking
A key must be revocable within minutes.
Rate limit
At least 60 requests per minute.
Response time
Within 60 seconds per request. See Response time.
CORS
Not needed. Every request is server-to-server.
AdPage calls the feed once a week, on Tuesday at 05:00 UTC, and asks for the last two years again each time, in blocks of 13 weeks: about 16 requests per run. Right after connecting, the history is fetched the same way.
Endpoints
The base URL is yours, for example https://api.yourcompany.com. The paths below are the defaults; different paths can be set when connecting.
GET /livez — reachability check
No authentication. Answers 200 with:
Optional, but strongly recommended: without it, AdPage cannot tell an outage from a key problem.
GET /adpage/v1/weekly-revenue — revenue per week per channel
date_from
yes
YYYY-MM-DD
Start of the range
date_to
yes
YYYY-MM-DD
End of the range
Response 200 is a JSON array with one object per week × channel:
iso_year
integer
yes
ISO year. Can differ from the calendar year of week_start.
iso_week
integer
yes
ISO week number, 1–53
week_start
date
yes
The Monday of the ISO week, YYYY-MM-DD
week
string
yes
For example "2026-W01"
revenue_excl_vat
number or numeric string
yes¹
Net revenue excluding VAT
vat
number or numeric string
no
VAT amount
revenue_incl_vat
number or numeric string
yes¹
Net revenue including VAT
cnt_receipts
integer
no
Number of receipts or orders
currency
string
no
ISO 4217, default EUR
location
string
no
Store or shop label, when there are several
country
string
no
Country of the customer, ISO 3166 alpha-2 (NL, DE). Empty means NL.
¹ At least one of the two. Supplying both is best. If you only supply the amount including VAT, AdPage converts it at 21%; tell support if a different rate applies.
Amounts may be a number or a numeric string with a dot as the decimal separator ("815883.62"). An empty array ([]) is a valid answer and means there is no data in the range.
Postcode split
postal_area is optional, and it changes the grain: one row per week × channel × postcode area instead of week × channel. It is what AdPage uses for regional analysis and geo experiments, and for a retailer with stores it is the only way to see store revenue by region.
It is the customer's postcode, not the store's. Four digits in the Netherlands (PC4). A store name belongs in
location.nullis a valid value and means it cannot be traced: an anonymous receipt, a guest order, an invalid postcode. That row still counts in full towards the weekly total. Keep it; do not drop it.The areas add up to the weekly total. Assign each receipt to exactly one area before counting, so that revenue and
cnt_receiptsper week and channel add up to the same figure as without the split.De-duplication includes the area:
(week_start, channel, country, postal_area).
Customers outside the Netherlands need country as well:
country
postal_area
Regional level
NL or empty
PC4, four digits (5384; 5384 AB also works)
12 provinces
DE
PLZ, five digits (52062)
16 Bundesländer
any other country
not read
none — it still counts in the weekly total
A value that does not look like a postcode of that country gets no region. Five digits without country are therefore not read as a Dutch postcode — that would quietly place a German customer in a Dutch province — and the sync reports how many rows that affected.
GET /adpage/v1/weekly-returns — returns per week per channel
Same parameters, same week rules. This endpoint is optional: if it answers 404, AdPage switches returns off for this connection and revenue keeps running.
iso_year, iso_week, week_start, week, channel
yes
As for revenue
return_value_excl_vat
number or numeric string
yes¹
Return value excluding VAT, as a positive amount
return_value_incl_vat
number or numeric string
yes¹
Return value including VAT, positive
return_items
integer
no
Number of items returned
currency, location
no
As for revenue
modified_at
datetime
yes
As for revenue
The Dutch values verwerkingsweek and besteldatum are accepted for date_basis too.
Channels
webshop
Online sales
Replaces the weekly figure AdPage measures itself through tracking. It is the same sales, measured better.
store
Physical store, till
Adds to the target: a different side of the business.
marketplace
Bol, Amazon and the like
Ignored by default; can be switched on per customer.
b2b
Business or dealer sales
Ignored by default.
online and ecommerce are read as webshop; retail and winkel as store. Any other value stays out of the target until support assigns it, and the connection test lists which channels it left out. Spell a channel the same way every time, in both endpoints.
The four rules
Almost everything that goes wrong with a connection like this goes wrong on one of these four.
1. Return whole ISO weeks
Every ISO week the range touches comes back in full. A week is never cut in half.
date_from=2026-01-01&date_to=2026-03-31 therefore returns 14 weeks: 2026-W01, which starts on Monday 29 December 2025, up to and including 2026-W14, which ends on Sunday 5 April 2026. That is slightly more than a calendar quarter, and that is intended.
Why: in a model, half a week looks like a week in which demand collapsed while the advertising budget stayed the same, and the model takes that entirely seriously. A boundary week too many is harmless; half a week is not.
2. The same week always returns the same figure
Adjacent ranges share their boundary week: Q1 and Q2 both contain 2026-W14. AdPage de-duplicates on week and channel, plus location, country and postal_area when you send them. Not on the week alone: then store and webshop would overwrite each other.
For you that means: return a week with the same amounts, whichever range asked for it. A week may only change when the data underneath it changes, and then rule 3 applies.
3. modified_at goes up when a row is revised
When something changes in an old week — a late payment, a correction, a rebooking — set modified_at again. When nothing changes, leave it alone.
AdPage asks for the last two years every week, so a correction comes through. When the same week comes back twice with different amounts, the row with the higher modified_at wins and the sync reports the conflict. Without modified_at, AdPage cannot tell a correction from a feed that drifts.
4. Say what is in the amount
The specification does not prescribe a business definition of revenue. It asks for one that is consistent and written down. Agree before you start:
Are services, shipping costs and gift cards included?
Are discounts already deducted?
Are returns already deducted from revenue, or do they only appear in the returns endpoint?
Which VAT basis, and which rate?
An example of a clear answer: article lines only — no services, no gift vouchers, no return costs or the discount lines that go with them; returns only in the returns endpoint.
The definition does not have to be elegant; it has to stay the same year after year. A definition that changes halfway is, to a model, an event it will try to explain.
Returns and date basis
processing_week
Grouped by the week in which the return was booked
order_week
Grouped by the week of the original order
The field is required because the difference is large and invisible from the outside. With processing_week, a return on an order from week 3 lands in week 8, so weekly revenue minus weekly returns is not that week's net revenue. That is why AdPage does not subtract returns from the target by default. Subtracting them is a deliberate choice per connection.
Error handling
200
OK
Processes the rows
401
Key missing or invalid
Not retried. The connection is marked as failing and the error shows on the tile.
403
Subscription suspended or blocked by policy
The same
404 on /weekly-returns
Endpoint not implemented
Returns switched off; revenue keeps running
400, 422
Invalid parameters
Not retried
429
Rate limit
Waits as long as Retry-After says (please send it), then tries again
5xx
Outage
Exponential backoff, at most four attempts; then the block is asked for again in two halves
3xx
Redirect
Treated as an error. Enter the final URL.
Response time
AdPage asks for 13 weeks at a time. If a block does not come back within 60 seconds, it is not retried as is but asked for again in two halves, down to a single week. That works, but it is slower. With the postcode split a response can be hundreds of times larger, so this is mainly something to watch there: an API that returns a quarter within half a minute is fetched in one go.
Test it yourself
With your own header name, replace Authorization: Bearer $TOKEN with that header.
Checklist
A feed that ticks this list connects to AdPage without custom work. For a review of your implementation or a test key from our side, contact support@adpage.io.
Was this helpful?

