Advert and order status synchronization
If you store OLX adverts in your own system, you need to know when their status changes on OLX — for example when an advert becomes active after moderation, expires, or is deleted. This article shows how to stay up to date by asking OLX only for adverts that changed, instead of downloading your whole advert set over and over.
1. Common approach: fetch everything
Many integrations sync statuses like this: every few minutes they page through GET /api/partner/adverts, fetch every advert (including inactive ones), and compare each one with their own data.
That works, but almost all of that work is wasted. Most of your adverts have not changed since the last check, and every run still downloads them all again.
Illustrative example
Imagine you have 5000 adverts and get 100 adverts per page. One full check needs 50 requests. If you repeat that every 5 minutes, that is 600 requests per hour — even if only 20 of your adverts changed in that time. These numbers are examples only, to illustrate the problem.
Fetching everything means:
- long syncs that load your servers
- a large amount of data to download, store, and compare
- a higher risk of hitting request limits (see FAQ)
- late detection of changes, because a full check of a large advert set takes time
It also loads OLX unnecessarily, because the same unchanged adverts are served again and again.
2. Better approach: advert change feed
Instead of asking “give me all my adverts”, ask: “which of my adverts changed since the last check?”. That is what the advert change feed answers:
GET /api/partner/status/advertsThe feed returns only identifiers of adverts that changed, starting with the oldest change. For each identifier you fetch the current advert with GET /api/partner/adverts/{advertId} and update its status in your system. If nothing changed, you get an empty list — one small request and you are done.
It is like a mailbox: you do not re-read every email to see what is new — you look only at new messages.
3. Before and after
Same example as above (illustrative data: 5000 adverts checked every 5 minutes, 20 adverts changed in an hour):
| Fetch everything | Advert change feed | |
|---|---|---|
| Requests per hour | 600 | 12 feed requests + 20 advert requests |
| What you download | All 5000 adverts, 12 times | A short list of identifiers and 20 changed adverts |
| When nothing changed | Full download anyway | One request with an empty list |
| Work on your side | Compare every advert | Update only changed adverts |
4. How the change feed works
The feed request takes these parameters:
| Parameter | Required | Description |
|---|---|---|
since | Yes | Moment from which you want to read changes, as an ISO-8601 datetime with timezone, for example 2026-05-11T10:00:00Z. You receive changes recorded strictly after that moment. Send the same value on every following request. |
cursor | No | The nextCursor value from the previous response. It tells the feed where the previous read ended. Omit this parameter only when you start reading from the since moment. |
limit | No | Maximum number of identifiers on one page. Default 100; values above 1000 are treated as 1000. |
Every response contains the same three fields:
data— identifiers of adverts that changed, starting with the oldest change. The list is empty when nothing changed.hasMore—truewhen more changes wait on the next page.nextCursor— your bookmark. It is always present, even whendatais empty.
Full contract is in the API Reference.
5. Synchronization step by step
Step 1: Start reading the feed
You already have your adverts in the system, for example from a one-time full download. For since, use a moment just before that download started, so you do not miss any change. Send the request without a cursor:
curl -H "Authorization: Bearer <token>" -H "Version: 2.0" "https://www.olx.bg/api/partner/status/adverts?since=2026-05-11T10:00:00Z"{
"data": ["1024578390", "1024578412"],
"hasMore": true,
"nextCursor": "MXwyMDI2LTA1LTExVDEwOjA0OjEyLjMzMVp8MTAyNDU3ODQxMg"
}Step 2: Read remaining pages
While hasMore is true, send the same since together with the received nextCursor as cursor:
curl -H "Authorization: Bearer <token>" -H "Version: 2.0" "https://www.olx.bg/api/partner/status/adverts?since=2026-05-11T10:00:00Z&cursor=MXwyMDI2LTA1LTExVDEwOjA0OjEyLjMzMVp8MTAyNDU3ODQxMg"{
"data": ["1024578455"],
"hasMore": false,
"nextCursor": "MXwyMDI2LTA1LTExVDEwOjA1OjAxLjEwMlp8MTAyNDU3ODQ1NQ"
}Step 3: Fetch only changed adverts
For each identifier in data, fetch the current advert and update its status in your system:
curl -H "Authorization: Bearer <token>" -H "Version: 2.0" "https://www.olx.bg/api/partner/adverts/1024578390"{
"data": {
"id": 1024578390,
"status": "active"
}
}Step 4: Check for changes regularly
When hasMore is false, your data is up to date. Store the last nextCursor. On the next check, send it as cursor (together with the same since). If nothing changed in the meantime, you get an empty list — still store the new nextCursor:
{
"data": [],
"hasMore": false,
"nextCursor": "MXwyMDI2LTA1LTExVDEwOjA1OjAxLjEwMlp8MTAyNDU3ODQ1NQ"
}Full loop in pseudocode
since = load("since") # the moment your full download started
cursor = load("cursor") # empty on the very first run
every few minutes:
repeat:
page = GET /api/partner/status/adverts?since=since&cursor=cursor
for each advertId in page.data:
ad = GET /api/partner/adverts/advertId
save the status of advertId in your system as ad.status
cursor = page.nextCursor
save("cursor", cursor)
until page.hasMore is false6. Practical tips
- Save the bookmark after every page. Store
sinceand the lastnextCursorsomewhere that survives a restart, for example in a database. After a pause or failure you resume exactly where you stopped — you miss nothing and you process nothing twice. - Use the cursor as-is. Do not decode, shorten, or invent cursor values — always send back the exact value you received.
- An empty list is good news. It means nothing changed. Still store
nextCursorfrom that response. - Changes appear with a small delay. A change becomes visible in the feed a few seconds after it happens, so a very fresh change may only show up on the next check.
- Pick a sensible page size. A smaller
limitmeans smaller responses; a larger one helps catch up faster after a longer pause. - Error handling. A
400response with codevalidation_errormeans the request is wrong — themessagefield points to which parameter. Fix the request instead of sending it again unchanged. If the cursor is rejected, start over by sending onlysincewith the moment of the last successful sync.
7. Key takeaways
- Do not download the whole advert set just to find a few that changed.
- Ask the change feed which adverts changed, then fetch only those adverts.
- Store
nextCursorafter every page — that is your bookmark. - An empty list means no changes — one small request instead of a full download.
More object types will follow later.