# Authorization in API
/docs/authorization-in-api
This guide covers OAuth authorization and tokens used by the **Application**. For who is a **Partner**, **Application** (**Client**), and **User**, see [Partner, Application, and User](/docs/partner-application-user).
## Authorization flow [#authorization-flow]
When the **Application** needs to act on behalf of a **User**, the **User** must grant access via OAuth:
## Operations [#operations]
After authorization, the **User** works only with the **Application**. The **Application** calls the OLX API with the stored `access_token`. The **User** never sends or receives that token:
## Tokens the Application uses [#tokens-the-application-uses]
In the authorization process the following items appear:
### User context — token with a specific User's context [#user-context--token-with-a-specific-users-context]
Used when the **Application** acts on behalf of a **User** (seller / lister).
- `authorization_code` — one-time code the **Application** receives after the **User** grants access to their OLX account. The **Application** exchanges this code for an `access_token` and a `refresh_token`.
- `access_token` — token the **Application** sends with API requests on behalf of that **User**. It has a limited lifetime (see `expires_in` in the token response). When it expires, the **Application** uses the `refresh_token` to get a new `access_token`. With a **User** `access_token` the **Application** can publish ads, read statuses, receive messages, and perform other user-scoped actions. A token for **User** John Doe cannot be used for **User** Jane Humbug, so each **User**'s inventory stays separate.
- `refresh_token` — token used in the **User** context to obtain a new `access_token` after the previous one expires. It lives longer than the access token. It can be used until it expires or is invalidated. The refresh flow may also return a new `refresh_token` — store it and use the latest one. If the `refresh_token` expires or is no longer valid, the **User** must go through authorization again to get a new `authorization_code`, and then a new `access_token` and `refresh_token`.
### Client context — token with the Application's context [#client-context--token-with-the-applications-context]
Obtained with grant type `client_credentials`. These tokens have no **User** context. They are used for operations that do not need a **User**'s data — for example categories, locations, and other data shared across **Users**.
- `access_token` — token the **Application** sends with API requests in the **Application** (**Client**) context. It also has a limited lifetime; when it expires, the **Application** requests a new one with `client_id` / `client_secret` and `grant_type: client_credentials`. There is no `refresh_token` in this flow. This token cannot perform actions on behalf of a **User** — only access shared resources.
- `client_id` / `client_secret` — **Application** credentials from the Developer Portal. Together with `grant_type: client_credentials` they are used to obtain a **Client**-context token. (`client_credentials` is the grant type name, not the secret itself.)
For request details, endpoints, and scopes, see the [API Reference](/api-reference). To register as a **Partner** and create an **Application**, follow [Getting access to API](/docs/getting-access-to-api).
---
# FAQ
/docs/faq
For error messages, see [Troubleshooting](/docs/troubleshooting).
## How do I set or change the redirect URI (callback URL)? [#callback-url]
Go to "Your apps", click "Edit" next to the app, fill in "Redirect URI" and click "Save changes". The URI must use HTTPS and must not point to `localhost`. To register more than one URI, separate them with a space. With more than one URI, you must send `redirect_uri` in the authorization request (see [Grant type: authorization_code](/api-reference#description/grant-type-authorization-code) in the API reference).
## Can I use the API to read other people's adverts? [#read-other-ads]
No. You can manage only the adverts of OLX accounts that connected your app through the `authorization_code` flow.
## Can I manage adverts in more than one country? [#multiple-countries]
Yes, but each country needs its own credentials. A `client_id` and `client_secret` work on one site only. To work in another country, sign in to the Developer Portal of that country with an OLX account from that country and register an app there.
| Country | Site |
| ---------- | ------ |
| Poland | olx.pl |
| Bulgaria | olx.bg |
| Romania | olx.ro |
| Portugal | olx.pt |
| Ukraine | olx.ua |
| Kazakhstan | olx.kz |
## Is there a test environment? [#test-environment]
No. To test, create a separate OLX account, connect it to your app and run your requests against that account.
## In which categories can I post adverts? [#ad-categories]
It depends on the country. Some categories are closed to the API, for example real estate or free categories in Poland. If you are not sure about a category, [contact us](/contact) before you build around it.
Categories open for posting in Poland:
- 4 (Praca)
- 5 (Motoryzacja)
- 87 (Moda)
- 88 (Dla Dzieci)
- 99 (Elektronika)
- 103 (Zwierzęta)
- 628 (Dom i Ogród)
- 751 (Muzyka i Edukacja)
- 757 (Rolnictwo)
- 767 (Sport i Hobby)
- 4371 (Usługi)
## Is there a request limit? [#request-limit]
Yes: 4500 requests per IP address within 5 minutes. Above that, the IP is blocked for 30 minutes and every request returns a 403 page. See [Troubleshooting](/docs/troubleshooting#rate-limits) for what the block looks like and what to do.
---
# Get access to the API
/docs/getting-access-to-api
To call the Partner API you need an approved app, which gives you a client ID and a client secret. You need an OLX account on the site you want to integrate with (credentials work for one country only). Registration takes a few minutes; approval is done by OLX and you get the result by email.
## 1. Sign in with your OLX account [#1-sign-in-with-your-olx-account]
1. Click "Sign in" in the top menu. You are redirected to the OLX login page.
2. Log in with your OLX account.
3. On your first sign-in, OLX asks you to allow the Developer Portal to access your OLX account. Allow it to continue.
## 2. Fill in your partner details [#2-fill-in-your-partner-details]
The first time you sign in, the portal opens the "Partner details" form. Fill in:
- Company: "Company name", "Tax ID", "Main purpose of the app", "Main activity area", "Website URL"
- Contacts: "Application owner", "Business contact email", "Technical contact email", "Phone number"
Under "Terms and privacy", tick "I've read and agree to the terms and conditions", then click "Save and continue".
## 3. Add your app [#3-add-your-app]
Fill in the app form and click "Add app":
| Field | What to enter |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| App name | Your app's name. |
| App website URL | Your product's website. |
| App description | What the app will do with the OLX API. We use it to review your request. |
| Redirect URI | Where OLX sends users after they sign in, for the `authorization_code` flow. It must use HTTPS and be publicly reachable; `localhost` addresses are rejected. |
To add more apps later, go to "Your apps" and click "Add an app".
## 4. Wait for approval [#4-wait-for-approval]
Your app appears under "Your apps" with the status "waiting for acceptance" while we review it. We email you when the review is done. The status then changes to "active" or "declined". If your app was declined and you don't know why, use the [contact form](/contact).
## 5. Get your credentials [#5-get-your-credentials]
When the app is "active", "Your apps" shows its credentials:
- **Client ID** (`client_id`): click the copy button next to it.
- **Client secret** (`client_secret`): click the eye icon to reveal it, or copy it directly. Keep it on your server only; anyone with the secret can request tokens for your app.
Other actions on the app:
- "Edit": change the name, website or redirect URI.
- "Rotate secret": replaces the client secret immediately. The old secret stops working, so update your integration right after rotating.
- "Delete": removes the app and its credentials.
## Next step [#next-step]
Use the client ID and secret to get an access token. The flow is described under [Authentication](/api-reference#description/authentication) in the API reference.
---
# Introduction
/docs
The OLX Partner API lets your software publish and manage adverts, handle orders and reply to buyers through OLX messaging on . Each OLX country is a separate site with its own credentials. To start you need an OLX account on this site and an approved app in this portal.
## Guides [#guides]
Read them in this order if you are new:
1. [Partner, Application, and User](/docs/partner-application-user) — who registers, who authorizes, and what "Client" means
2. [Get access to the API](/docs/getting-access-to-api): register an app and get your client ID and secret.
3. [Authorization in API](/docs/authorization-in-api) — OAuth flow, User-context and Client-context tokens
4. [Advert and order status synchronization](/docs/status-synchronization): poll only the adverts that changed instead of re-fetching all of them.
5. [Order management](/docs/order-management): find changed orders, read their state and act on them.
When something goes wrong:
- [Troubleshooting](/docs/troubleshooting): common errors, their causes and fixes.
- [FAQ](/docs/faq): access, countries, testing, categories and request limits.
## API reference [#api-reference]
The [API reference](/api-reference) has every endpoint with its parameters, request and response schemas, and status codes. Use it when you know which call you need and want the exact fields.
---
# Partner, Application, and User
/docs/partner-application-user
**Important:** In Partner API docs, **Client** means the **Application** (the HTTP / OAuth client), not a person and not the customer who pays for a product. Do not confuse **Client** with **User** (also called seller or lister).
## Glossary [#glossary]
**Partner** — the company that builds the integration. The **Partner** is responsible for following the Partner API Terms & Conditions, for the technical solution, and for technical contact related to the integration.
**Application** (also called **Client** in the API) — software created by the **Partner** that calls the Partner API to integrate with OLX. One **Partner** may own several **Applications**. Each **Application** has its own credentials (`client_id` / `client_secret`). End users work with the **Partner**'s product; the **Application** is what talks to OLX on their behalf.
**User** (also called seller or lister) — a person who uses the **Partner**'s **Application** and has an OLX account. Through the **Application**, the **User** can publish ads, read statuses and messages, and use other OLX features without using the OLX website or app directly. When the API acts "on behalf of a user", it means this OLX account — not the **Partner** company.
**Relationship:**
```text
Partner → owns Application(s) / Client(s) → each Application acts on behalf of User(s) (sellers / listers)
```
## Example [#example]
**Partner** _Excellent and Beautiful Integrations Company (EBIC)_ creates two **Applications**:
- Excellent Stock Management
- Excellent Stock Management Premium
These **Applications** help EBIC's customers manage inventory. One feature is selling on OLX.
For an EBIC customer to sell on OLX, that person must have an OLX account. In API terms they are a **User** (seller / lister) — not a **Client**.
The **User** signs in to Excellent Stock Management (or Premium) and grants that **Application** access to their OLX account (OAuth consent, started by the **Application**). After consent, the **Application** can publish ads, read ad statuses, receive buyer messages, and use other Partner API features in that **User**'s name. The **Application** stores that **User**'s tokens on its side.
In their OLX account, the **User** can see connected **Applications** and disconnect one at any time. After disconnect, that **Application** can no longer use their OLX account. A **User** may connect **Applications** from several **Partners**.
## Who registers in the Developer Portal? [#who-registers-in-the-developer-portal]
The **Partner** registers in the Developer Portal (Partner API Terms & Conditions must be accepted). Then the **Partner** registers their **Applications** (**Clients**). Each **Application** gets a `client_id` and `client_secret` used in OAuth. The **Partner** manages **Applications**, settings, and API usage.
The **User** does not register in the Developer Portal. **Users** use the **Partner**'s **Application** and authorize it to access their OLX account. They are onboarded through the auth / consent flow, not through the portal.
**Common mix-ups to avoid**
- The paying customer of the **Partner**'s product is a **User** (seller / lister), not a **Client**.
- **Client** in the API always means the **Application**.
- Do not register end sellers in the Developer Portal as if they were **Partners**.
For OAuth, tokens, and how the **Application** calls the API on behalf of a **User**, see [Authorization in API](/docs/authorization-in-api).
For request details, endpoints, and scopes, see the [API Reference](/api-reference). To register as a **Partner** and create an **Application**, follow [Getting access to API](/docs/getting-access-to-api).
---
# Advert and order status synchronization
/docs/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 [#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](/docs/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 [#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 [#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 [#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` — `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](/api-reference).
### 5. Synchronization step by step [#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:
" \
-H "Version: 2.0" \
"https://{SITE_HOST}/api/partner/status/adverts?since=2026-05-11T10:00:00Z"`}
/>
```json
{
"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`:
" \
-H "Version: 2.0" \
"https://{SITE_HOST}/api/partner/status/adverts?since=2026-05-11T10:00:00Z&cursor=MXwyMDI2LTA1LTExVDEwOjA0OjEyLjMzMVp8MTAyNDU3ODQxMg"`}
/>
```json
{
"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:
" \
-H "Version: 2.0" \
"https://{SITE_HOST}/api/partner/adverts/1024578390"`}
/>
```json
{
"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`:
```json
{
"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 [#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 [#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.
The same approach applies to orders — see [Order Management](/docs/order-management) and the order change feed.
More object types will follow later.
---
# Troubleshooting
/docs/troubleshooting
Each section starts with the error as you see it. If your error is not listed or the fix does not help, use the [contact form](/contact) and include the request, the full response and its Request ID if there is one.
## "Invalid owner in token" [#invalid-owner-in-token]
**Cause:** you called an endpoint that acts on an OLX user's account (for example adding an advert or checking the account balance) with a token from the `client_credentials` grant. That token belongs to your app, not to a user.
**Fix:** get a token with the `authorization_code` grant for the user whose account you want to use. See [Grant type: authorization_code](/api-reference#description/grant-type-authorization-code) in the API reference.
## "The grant type is unauthorized for this client_id" [#grant-type-unauthorized]
**Cause:** your app is not allowed to use the `grant_type` you sent, or the value is misspelled.
**Fix:** check that `grant_type` is exactly one of `authorization_code`, `client_credentials` or `refresh_token`, and that you send the `client_id` of the right app. If the value is correct and the error persists, [contact us](/contact) with your `client_id`.
## Refresh token expired [#refresh-token-expired]
**Cause:** a refresh token is valid for 30 days (2592000 seconds), and there is no refresh token that never expires. A refresh can also return a new refresh token, and integrations that keep using the first one eventually send an expired token.
**Fix:** after every refresh, store the `refresh_token` from the response and use it next time. If the token has already expired, the user must connect their account again through the `authorization_code` flow. See [Grant type: refresh_token](/api-reference#description/grant-type-refresh-token-when-access-token-is-expired) in the API reference.
## "Missing required header" [#missing-required-header]
**Cause:** the request has no `Version` header.
**Fix:** send `Version: 2.0` with every Partner API request:
## 400 Bad Request on a GET request [#content-type-header]
**Cause:** the GET request has a `Content-Type: application/json` header. GET requests have no body, and the API rejects them with this header.
**Fix:** send `Content-Type: application/json` only on requests with a JSON body (POST, PUT). Remove it from GET requests.
## 403 "The request could not be satisfied" [#rate-limits]
You get an HTML page instead of JSON:
```text
403 ERROR
The request could not be satisfied.
Request blocked. We can't connect to the server for this app or website at this time.
...
Generated by cloudfront (CloudFront)
Request ID: sY4_bCTYW2pwfH5dGXYjdY1843RY6uKYMLSsxy2dDJS9_JbTqrITGw==
```
**Cause:** your IP address sent more than 4500 requests within 5 minutes. Requests from that IP are then blocked for 30 minutes.
**Fix:**
- Wait 30 minutes; the block lifts on its own.
- Keep your request rate below 4500 requests per 5 minutes per IP. To sync statuses without re-fetching every advert, use the [change feed](/docs/status-synchronization).
- If you are still blocked after 30 minutes, or you are sure you stayed under the limit, [contact us](/contact) with the IP address you send requests from and the Request ID from the error page.