Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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.

AdPage never asks for personal data, orders, order lines or write access. Three GET endpoints, one key, weekly totals.

Transport and authentication

Topic
Requirement

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

Parameter
Required
Format
Meaning

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:

Field
Type
Required
Description

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"

channel

string

yes

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

postal_area

string or null

no

Postcode area of the customer. See Postcode split

country

string

no

Country of the customer, ISO 3166 alpha-2 (NL, DE). Empty means NL.

modified_at

datetime

yes

When the row was last put together. See the four rules

¹ 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.

  1. It is the customer's postcode, not the store's. Four digits in the Netherlands (PC4). A store name belongs in location.

  2. null is 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.

  3. The areas add up to the weekly total. Assign each receipt to exactly one area before counting, so that revenue and cnt_receipts per week and channel add up to the same figure as without the split.

  4. 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.

Field
Type
Required
Description

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

date_basis

string

yes

processing_week or order_week. See Returns and date basis

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

Value
Meaning
What AdPage does with it

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

Value
Meaning

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

Status
Meaning
What AdPage does

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?