Skip to content

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/adverts

The 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 everythingAdvert change feed
Requests per hour60012 feed requests + 20 advert requests
What you downloadAll 5000 adverts, 12 timesA short list of identifiers and 20 changed adverts
When nothing changedFull download anywayOne request with an empty list
Work on your sideCompare every advertUpdate only changed adverts

4. How the change feed works

The feed request takes these parameters:

ParameterRequiredDescription
sinceYesMoment 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.
cursorNoThe 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.
limitNoMaximum 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 — true when more changes wait on the next page.
  • nextCursor — your bookmark. It is always present, even when data is 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 false

6. Practical tips

  • Save the bookmark after every page. Store since and the last nextCursor somewhere 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 nextCursor from 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 limit means smaller responses; a larger one helps catch up faster after a longer pause.
  • Error handling. A 400 response with code validation_error means the request is wrong — the message field points to which parameter. Fix the request instead of sending it again unchanged. If the cursor is rejected, start over by sending only since with 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 nextCursor after 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.