> For the complete documentation index, see [llms.txt](https://docs.adpage.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.adpage.io/data-and-insights/marketing-integrations/adpage-feed-your-own-api/technical-specification.md).

# 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)](https://docs.adpage.io/data-and-insights/marketing-integrations/adpage-feed-your-own-api.md).

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.

{% hint style="info" %}
AdPage never asks for personal data, orders, order lines or write access. Three GET endpoints, one key, weekly totals.
{% endhint %}

## 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](#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:

```json
{ "status": "ok" }
```

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   |

```bash
curl -s "https://api.yourcompany.com/adpage/v1/weekly-revenue?date_from=2026-01-01&date_to=2026-03-31" \
  -H "Authorization: Bearer $TOKEN"
```

Response `200` is a JSON array with one object per week × channel:

```json
[
  {
    "iso_year": 2026,
    "iso_week": 1,
    "week_start": "2025-12-29",
    "week": "2026-W01",
    "channel": "store",
    "revenue_excl_vat": "815883.62",
    "vat": "171257.26",
    "revenue_incl_vat": "987140.88",
    "cnt_receipts": 4590,
    "modified_at": "2026-08-17T02:44:13.885131"
  }
]
```

| 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      | See [Channels](#channels)                                                     |
| `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](#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](#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](#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

```bash
export TOKEN="your-key"
export BASE="https://api.yourcompany.com"

# 1. Reachable?
curl -s "$BASE/livez"

# 2. Revenue over a quarter
curl -s "$BASE/adpage/v1/weekly-revenue?date_from=2026-01-01&date_to=2026-03-31" \
  -H "Authorization: Bearer $TOKEN" | jq 'length, .[0]'

# 3. Boundary weeks: does the first week start BEFORE date_from?
curl -s "$BASE/adpage/v1/weekly-revenue?date_from=2026-01-01&date_to=2026-03-31" \
  -H "Authorization: Bearer $TOKEN" | jq -r '.[0].week, .[0].week_start'
# expected, for example: "2026-W01" and "2025-12-29"

# 4. Stability: the same week from two ranges, the same amount?
for R in "2026-01-01 2026-03-31" "2026-04-01 2026-06-30"; do
  set -- $R
  curl -s "$BASE/adpage/v1/weekly-revenue?date_from=$1&date_to=$2" \
    -H "Authorization: Bearer $TOKEN" \
    | jq -r '.[] | select(.week=="2026-W14") | "\(.week) \(.channel) \(.revenue_incl_vat)"'
done
# both blocks must be identical

# 5. Without a key you should get 401
curl -s -o /dev/null -w '%{http_code}\n' "$BASE/adpage/v1/weekly-revenue?date_from=2026-01-01&date_to=2026-01-31"
```

With your own header name, replace `Authorization: Bearer $TOKEN` with that header.

## Checklist

* [ ] HTTPS only, `GET` only, no redirects
* [ ] Key in a header; a primary and a secondary key, both valid
* [ ] `/livez` without authentication
* [ ] `/adpage/v1/weekly-revenue` with `date_from` and `date_to`
* [ ] Whole ISO weeks, boundary weeks in full
* [ ] One row per week × channel (× `location`) (× `postal_area`)
* [ ] With `postal_area`: the areas add up to the weekly total, and `null` still counts
* [ ] Customers outside the Netherlands: `country` sent (`DE` with a five-digit PLZ)
* [ ] The same week always returns the same amounts
* [ ] `modified_at` on every row, raised on revision
* [ ] `revenue_excl_vat` and/or `revenue_incl_vat`
* [ ] `channel` from a fixed, consistent set
* [ ] Optional: `/adpage/v1/weekly-returns` with the required `date_basis`
* [ ] `Retry-After` on `429`
* [ ] The business definition of revenue written down

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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.adpage.io/data-and-insights/marketing-integrations/adpage-feed-your-own-api/technical-specification.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
