OLX Marketplace Sync

Sync stock and prices with OLX adverts

OLX by Koda Plus

Connect an OLX seller account to Medusa and keep both sides honest. The plugin reads your OLX adverts, links every advert to the right product variant by SKU, and shows in the Medusa admin where OLX and the store disagree: adverts live while the variant is sold out or the product unpublished, stock that is not live on OLX, products never listed. It reads advert statistics and unread conversations, and gives your storefront live advert links.

Writes are opt-in. Three writers, off until you allow them in the options and arm them in the admin, can end adverts that sold out and bring them back, keep advert prices in line with Medusa, and publish products as new adverts. Each one plans first, shows a dry run, applies a capped number of changes per run and looks the advert up on OLX before every write.

Live demo: Medusa admin medusa.koda.plus/app/olx, signed in to a public demo account by the link itself, and the storefront demo.koda.plus. The demo runs the plugin in demo mode: a simulated OLX account built from the store catalog, with alerts, statistics, conversations and all three writers acting on the simulation.

What it syncs

Seller account (OAuth 2.0): OLX to Medusa, when you click Connect OLX account. Scope Copy to clipboardread v2, plus Copy to clipboardwrite only when a writer is allowed in the options.
Adverts (id, title, URL, status, price, category, Copy to clipboardexternal_id, the SKU from the description): OLX to Medusa, every hour at minute 30 and on Sync now.
Advert to variant links, one primary advert per variant: inside Medusa, on every sync.
Alerts: Medusa stock, prices and product status against the advert snapshot, every 15 minutes.
Statistics (views, phone views, observers): OLX to Medusa, every hour at minute 45, oldest first.
Message threads (unread and total counts per conversation): OLX to Medusa, every 15 minutes.
Advert lifecycle, prices, new adverts: Medusa to OLX, only from an armed writer.
Live advert links for an "Also on OLX" button: Medusa to your storefront through Copy to clipboardGET /store/olx/products/:id.

Features

OLX page in the admin with two views switched in the header: Panel and Setup guide (also as Copy to clipboard?view=guide, so a link can open the guide directly).
Counters for adverts (live, over the package limit, ended, products live on OLX, live adverts without a product, adverts without SKU), alerts, statistics totals and unread messages.
Alerts in four kinds, with filters and search: live on OLX but sold out in the store, live but not published, in stock but not live on OLX, in stock and never on OLX.
Advert lifecycle writer: ends live adverts whose variant sold out or whose product is no longer published, finishes sold out adverts over the package limit, and brings back the adverts it ended itself when the stock returns.
Price writer: sets live advert prices to the variant's base price in the market currency; changes above a limit wait for your approval.
Publishing: one advert per variant, built from the product (title, description, price, images), the category mapping and the category's required attributes read from OLX. The publish plan shows the exact request, or what is missing.
Statistics per advert in the advert table and the product widget, totals in the counters.
Messages: unread conversations linked to adverts and products, with links to the advert and the OLX chat inbox. Counts only, no message text.
Product widget on every product page: its adverts with status, price, statistics and unread messages, its alerts and its publish state, or how to link an advert.
Setup guide in the admin: the rollout from zero to production with live step states, a diagram, a go-live checklist and troubleshooting, in English and Polish.
Running in production: stores that use the plugin, from the Copy to clipboardreferences option, on the Panel and in the guide.
SKU matching by Copy to clipboardexternal_id first (what feeds, BaseLinker and this plugin fill in), then by a configurable SKU line in the description such as Copy to clipboardKod produktu: KS-ELN-18V. Case-insensitive, never by title.
Safe incomplete reads: an incomplete read adds and updates but removes nothing, and plans nothing new.
Demo mode: a simulated OLX account from your own catalog runs through the same parsers, plans and writers. Evaluate everything without an OLX developer account.
Admin in English and Polish through the Medusa admin translations.
Workflows included for the sync, the plan cycle, every writer, statistics and threads.

Write safety

Two switches per writer. The option (Copy to clipboardlifecycleWriter, Copy to clipboardpriceWriter, Copy to clipboardpublishWriter) is the hard one: Copy to clipboardfalse wins and the admin cannot override it. The switch in the admin is the runtime one, stored with who flipped it and when. In live mode the OLX token must also carry the Copy to clipboardwrite scope. Demo toggles and live toggles are separate.
Plan first. Every 15 minutes a plan says what each writer would change, from what to what. The admin shows it, and Dry run lists the exact requests a run would send. Nothing is planned from an incomplete read or when Medusa stock could not be read, and an advert missing from a read is never treated as ended.
Look before you write. Every item is read on OLX right before its write. Already done: adopted, nothing sent. No longer applicable (a person ended the advert, the price changed on OLX meanwhile): skipped, and the snapshot learns the fresh fact.
One write per item per run, a cap per run (Copy to clipboardmaxLifecycleActionsPerRun, Copy to clipboardmaxPriceUpdatesPerRun, Copy to clipboardmaxPublishPerRun) and quarantine after three rejections in a row, until a person releases the item.
Unclear answers are never retried blindly. A timeout or a 5xx after a write leaves the item Copy to clipboardunknown; the next run reads the advert first and decides.
Publishing exactly once per variant: a unique row per variant before anything goes out, an atomic claim with a lease, a lookup of the SKU in Copy to clipboardexternal_id before every create, a second lookup after an unclear answer, and a new create only when a lookup a quarter of an hour later still finds nothing.
Mass guard. A lifecycle plan that would end more than max(10, 25 %) of the live linked adverts looks like a broken stock import: scheduled runs end nothing until a person runs it deliberately.
Only what the plugin was meant to do. A write barrier lets through GET and HEAD, the OAuth token exchange, and three writes only for the writer armed for the call: advert commands Copy to clipboardactivate, Copy to clipboarddeactivate and Copy to clipboardfinish, an advert update, a new advert. Deleting adverts, buying packets or paid features, the Copy to clipboardextend command and messages are refused by the code.
Reactivates only its own pauses. The lifecycle writer brings back only adverts it ended itself, never one a person ended.

Requirements

Medusa 2.12 or newer (tested on 2.15.3) and Node.js 20+.
For a real account: an application registered and accepted in the OLX developer portal of your market (for Poland developer.olx.pl), with your callback URL. OLX reviews applications, and the API terms are for business use.

Installation

1
npm install @koda-plus/medusa-plugin-olx

Yarn and pnpm work the same way: Copy to clipboardyarn add @koda-plus/medusa-plugin-olx or Copy to clipboardpnpm add @koda-plus/medusa-plugin-olx.

Configuration

Add the plugin to Copy to clipboardmedusa-config.ts:

1234567891011121314151617181920
module.exports = defineConfig({
  // ...
  plugins: [
    {
      resolve: "@koda-plus/medusa-plugin-olx",
      options: {
        clientId: process.env.OLX_CLIENT_ID,
        clientSecret: process.env.OLX_CLIENT_SECRET,
        encryptionKey: process.env.OLX_ENCRYPTION_KEY,
        redirectUri: "https://api.your-store.com/olx/callback",
        market: "pl",
        // Writers: off unless allowed here AND armed in the admin.
        lifecycleWriter: process.env.OLX_LIFECYCLE_WRITER === "true",
        priceWriter: process.env.OLX_PRICE_WRITER === "true",
        publishWriter: process.env.OLX_PUBLISH_WRITER === "true",
        // demo: true, // a simulated OLX account from your catalog, no OLX account needed
      },
    },
  ],
})

Set the credentials in Copy to clipboard.env. Generate the encryption key with Copy to clipboardopenssl rand -base64 32:

123
OLX_CLIENT_ID=your-client-id
OLX_CLIENT_SECRET=your-client-secret
OLX_ENCRYPTION_KEY=base64-encoded-32-bytes

Run the migrations, then open OLX in the admin sidebar:

1
npx medusa db:migrate

Options

Connection:

Copy to clipboardclientId: OLX application client id.
Copy to clipboardclientSecret: OLX application client secret.
Copy to clipboardencryptionKey: 32 random bytes in base64. Encrypts OLX tokens at rest with AES-256-GCM.
Copy to clipboardredirectUri: must equal a callback URL registered in the OLX application. The plugin serves it at Copy to clipboard/olx/callback.
Copy to clipboardmarket (default Copy to clipboardpl): Copy to clipboardpl, Copy to clipboardro, Copy to clipboardpt, Copy to clipboardbg, Copy to clipboardua, Copy to clipboardkz or Copy to clipboarduz.
Copy to clipboarddemo (default Copy to clipboardfalse): a simulated OLX account generated from your catalog. Nothing is sent to OLX.

Reading:

Copy to clipboardskuPatterns (default: lines starting with Copy to clipboardKod produktu, Copy to clipboardProduct code or Copy to clipboardSKU): regex sources with one capture group that find the SKU in descriptions.
Copy to clipboardsyncEnabled (default Copy to clipboardtrue): the hourly sync and the 15 minute plan.
Copy to clipboardsalesChannelId (default: every stock location): count stock only at the stock locations of this sales channel.
Copy to clipboardstatsEnabled (default Copy to clipboardtrue): the hourly statistics refresh.
Copy to clipboardstatsPerRun (default Copy to clipboard200): adverts whose statistics one run refreshes; each advert at most every six hours.
Copy to clipboardmessagesEnabled (default Copy to clipboardtrue): the 15 minute read of message threads.
Copy to clipboardrequestsPerMinute (default Copy to clipboard200): self-imposed rate limit. OLX blocks an IP for 30 minutes after 4 500 requests in 5 minutes.
Copy to clipboardtimeoutMs (default Copy to clipboard20000): timeout of one OLX request.

Writers (all off by default in live mode; in demo mode they default to on and act on the simulation only):

Copy to clipboardlifecycleWriter (default Copy to clipboardfalse): allows the advert lifecycle writer.
Copy to clipboardpriceWriter (default Copy to clipboardfalse): allows the price writer.
Copy to clipboardpublishWriter (default Copy to clipboardfalse): allows publishing.
Copy to clipboardmaxLifecycleActionsPerRun (default Copy to clipboard20), Copy to clipboardmaxPriceUpdatesPerRun (default Copy to clipboard20), Copy to clipboardmaxPublishPerRun (default Copy to clipboard5): caps of one run.
Copy to clipboardmaxPriceChangePercent (default Copy to clipboard50): larger price changes wait for your approval in the admin.
Copy to clipboarddeactivateAsSold (default Copy to clipboardfalse): the Copy to clipboardis_success flag sent with Copy to clipboarddeactivate (whether the item sold through OLX). The plugin cannot know where an item sold, so it says no unless you choose otherwise.

Publishing (Copy to clipboardpublish):

Copy to clipboardpublish.categories: Copy to clipboard[{ medusaCategory, olxCategoryId, attributes? }]. Copy to clipboardmedusaCategory is a Medusa product category id or handle, Copy to clipboardolxCategoryId a leaf OLX category, Copy to clipboardattributes default values for it, such as Copy to clipboard{ state: "new" }.
Copy to clipboardpublish.attributes: attribute values for every category.
Copy to clipboardpublish.location: Copy to clipboard{ cityId, districtId?, latitude?, longitude? }, city id from Copy to clipboardGET /cities or Copy to clipboardGET /locations of the Partner API.
Copy to clipboardpublish.contact: Copy to clipboard{ name, phone? } shown on the advert.
Copy to clipboardpublish.advertiserType (default Copy to clipboardbusiness).
Copy to clipboardpublish.descriptionFooter: appended to every description, for example delivery and returns.
Per product, in Medusa metadata: Copy to clipboardolx_title, Copy to clipboardolx_category_id and Copy to clipboardolx_attributes (an object of attribute codes and values; on a variant it wins over the product).

Presentation:

Copy to clipboardreferences: stores running the plugin, shown as "Running in production". Each entry: Copy to clipboardname, Copy to clipboardurl (https), and optionally Copy to clipboarddescription (a string, or Copy to clipboard{ en, pl }), Copy to clipboardmetrics (Copy to clipboard[{ label, value }]) and Copy to clipboardlinks (Copy to clipboard[{ label, url }]). A store that starts on Medusa soon gets Copy to clipboardsoon: true: it is shown with a "Soon" badge and no link, and its Copy to clipboardurl is optional. Entries without a name, or live entries without an https URL, are dropped; nothing here can break the boot.

Missing options never break the boot: the module registers, the admin lists what is missing and the jobs wait.

Connecting the account

In the OLX developer portal, register an application and put your callback URL into its "Adres powrotu" field, for example Copy to clipboardhttps://api.your-store.com/olx/callback.
In the Medusa admin open OLX and click Connect OLX account. A consent page of OLX opens, valid for 15 minutes.
The seller, logged in to OLX, approves access. OLX redirects to Copy to clipboard/olx/callback, the plugin exchanges the code (valid 10 minutes) for tokens and starts the first sync.

The access token lives 24 hours and the refresh token one month. Both are renewed by the hourly sync. If you allow a writer later, connect the account again so the token carries the Copy to clipboardwrite scope.

Setup in brief

The admin has the full guide (OLX, Setup guide), with the state of every step taken from your store.

Register an application in the OLX developer portal and wait for the acceptance e-mail.
Set the callback URL of the application to your Copy to clipboard/olx/callback address.
Add the plugin options and the environment variables, then restart.
Run Copy to clipboardnpx medusa db:migrate.
Connect the OLX account from the admin.
Run the first read with Sync now.
Make sure the adverts carry the SKU: Copy to clipboardexternal_id, or a Copy to clipboardKod produktu: SKU line in the description.
Read the alerts and fix what they show.
Allow one writer in the options, connect again for the write scope, run Dry run, read every line, then arm it. One writer at a time.
For publishing, map categories, set the location and the contact, and check the publish plan.
Walk the go-live checklist; from then on the jobs run by themselves.

How matching works

Every advert gets a key: its Copy to clipboardexternal_id, or, when that is empty, the SKU found in the description by Copy to clipboardskuPatterns. Both sides are compared uppercased and trimmed.
The key is looked up among variant SKUs. A variant can have several adverts (a re-listed item, an old ended one); the primary advert wins by status (live, then over the limit, then ended) and then by the newest advert id.
A complete read replaces the snapshot. An incomplete read (a failed page, the 5 000 advert ceiling) only adds and updates.

Alerts

Recomputed every 15 minutes from the last complete read and the current Medusa catalog:

Live, sold out: the advert is live while its variant has no stock.
Live, not published: the advert is live while the product is a draft, proposed or rejected.
In stock, not live: the variant has stock and adverts, but none of them is live (ended, over the package limit, removed). Adverts in moderation count as on their way.
In stock, not on OLX: published, in stock, with a SKU, and never on OLX.

Stock must be a fact: a variant that tracks inventory but has no inventory item raises nothing, and nothing is acted on. Variants that do not manage inventory, or allow backorders, count as in stock.

Writers

Advert lifecycle (Copy to clipboardPOST /adverts/{id}/commands): Copy to clipboarddeactivate for live adverts of sold out or unpublished variants, Copy to clipboardfinish for sold out adverts over the package limit, Copy to clipboardactivate for adverts this plugin deactivated once their variant is back in stock and published. Adverts a person ended are never reactivated. Bringing an advert back uses your OLX package like a manual reactivation; an advert over the limit stays limited, and the plugin never buys packets.

Prices (Copy to clipboardPUT /adverts/{id}): the OLX update replaces the whole advert, so the writer reads the advert and sends every documented field back unchanged, only the price differs. The target is the variant's base price in the market currency (no price list, no rules, no quantity tier). A variant without one is skipped, never priced at zero. If the price on OLX changed after the plan, the item is skipped and planned again from the new price.

Publishing (Copy to clipboardPOST /adverts): candidates are published, in-stock variants with a SKU and no advert, in a mapped category. Title, description (plain text, a SKU line and your footer), price, https images up to the category limit, location, contact and the required attributes from Copy to clipboardGET /categories/{id}/attributes are checked against the OLX rules before anything is sent: title 16 to 150 characters, description 80 to 9 000, no e-mail addresses, web addresses or phone numbers, at most half capital letters. The SKU goes into Copy to clipboardexternal_id, so the next sync links the new advert to its variant.

Every run is recorded with its items, and the last dry run and the last applied run show on the writer card.

Statistics and messages

Statistics come from Copy to clipboardGET /adverts/{id}/statistics, one request per advert, at most Copy to clipboardstatsPerRun adverts an hour and each advert at most every six hours. The OLX API terms forbid presenting account statistics to others without OLX's permission, so they stay in the admin: no store route returns them.

Messages come from Copy to clipboardGET /threads. The plugin stores the thread key, the advert, the number of messages and of unread messages, the date and the favourite flag. It keeps no message text and no buyer id; conversations are read and answered on OLX.

API routes

Copy to clipboardGET /admin/olx: status, counters, alerts, statistics and message totals, writers, the last plan and the last run.
Copy to clipboardPOST /admin/olx/connect: starts connecting and returns the OLX consent URL.
Copy to clipboardPOST /admin/olx/disconnect: forgets the tokens.
Copy to clipboardPOST /admin/olx/sync: starts a sync, then the plan and the armed writers (202, in the background).
Copy to clipboardGET /admin/olx/adverts: the snapshot, with Copy to clipboardfilter (all, linked, unmatched, limited, ended, nokey), Copy to clipboardq, Copy to clipboardlimit and Copy to clipboardoffset.
Copy to clipboardGET /admin/olx/alerts: alerts, with Copy to clipboardkind, Copy to clipboardq, Copy to clipboardlimit and Copy to clipboardoffset.
Copy to clipboardGET /admin/olx/plan: plan rows of the lifecycle or price writer, with Copy to clipboardwriter and Copy to clipboardview (open, held, quarantined, done, all).
Copy to clipboardGET /admin/olx/publications: the publish plan and published adverts, with Copy to clipboardview (plan, ready, blocked, problems, published, all) and Copy to clipboardq.
Copy to clipboardGET /admin/olx/threads: message threads, with Copy to clipboardfilter (unread, all).
Copy to clipboardGET /admin/olx/runs: the sync history.
Copy to clipboardGET /admin/olx/writer-runs: dry and applied runs, with Copy to clipboardwriter.
Copy to clipboardGET /admin/olx/products/:id: adverts, alerts and publications of a product.
Copy to clipboardPOST /admin/olx/writers/:writer: Copy to clipboard{ armed: boolean }, the runtime switch of Copy to clipboardlifecycle, Copy to clipboardprice or Copy to clipboardpublish.
Copy to clipboardPOST /admin/olx/writers/:writer/run: Copy to clipboard{ dryRun?: boolean, overrideGuard?: boolean }. A dry run answers right away; an applied run needs the writer armed and runs in the background.
Copy to clipboardPOST /admin/olx/writers/:writer/items/:id/release: releases a quarantined item, approves a held price change, or lets a failed publication go again.
Copy to clipboardPOST /admin/olx/stats/refresh and Copy to clipboardPOST /admin/olx/threads/sync: refresh now (202).
Copy to clipboardPOST /admin/olx/demo/reset: demo mode only, starts the simulation over.
Copy to clipboardGET /store/olx/products/:id: live adverts of a product for the storefront (real adverts only, never statistics).
Copy to clipboardGET /olx/callback: the OAuth redirect URI. Public, and it only acts during a connection attempt.

No route deletes anything.

Jobs

Copy to clipboardolx-sync-adverts, every hour at :30: the sync, then the plan and the armed writers.
Copy to clipboardolx-plan, every 15 minutes (:05, :20, :35, :50): alerts, plans and the armed writers, without reading the advert list.
Copy to clipboardolx-refresh-stats, every hour at :45: statistics.
Copy to clipboardolx-sync-threads, every 15 minutes (:10, :25, :40, :55): message threads.

Workflows

12345678910111213
import {
  syncOlxAdvertsWorkflow,
  runOlxCycleWorkflow,
  runOlxWriterWorkflow,
  refreshOlxStatsWorkflow,
  syncOlxThreadsWorkflow,
} from "@koda-plus/medusa-plugin-olx/workflows"

await syncOlxAdvertsWorkflow(container).run({ input: { trigger: "manual" } })
await runOlxCycleWorkflow(container).run({ input: { trigger: "manual" } })
const { result } = await runOlxWriterWorkflow(container).run({
  input: { writer: "lifecycle", dryRun: true },
})

Security and data

Write barrier (see Write safety): reads, the token exchange and three narrow writes, each only for the writer armed for the call.
Encrypted tokens: AES-256-GCM with a random IV per write. The key lives in your environment, not in the database.
OAuth Copy to clipboardstate nonce: one-time, valid 15 minutes and compared literally, so nobody can attach a foreign OLX account through the public callback.
Masked logs: secrets and token-like strings are masked in logs, the database and the admin.
Rate limited, with retries only for transient errors on reads (network, 5xx, 429 with the server's wait), and a 30 minute pause of every job when OLX blocks the IP.
No buyer personal data at rest. The snapshot keeps no contact data, locations or images of adverts; threads keep counts only.

What this plugin does not do

It does not reply to messages or mark them as read; conversations stay on OLX.
It does not delete adverts, buy packets, buy paid features or extend adverts.
It does not change advert titles, descriptions, images or attributes after publishing; only the price writer edits a live advert, and only its price.
It does not publish job adverts (salary categories), set OLX Delivery options or send product safety (GPSR) data; categories that require them reject the advert and the plan shows OLX's message.
It does not handle OLX Delivery shipments or orders placed on OLX.
It does not move stock from OLX to Medusa: Medusa is the source of truth.
One OLX seller account and one market per Medusa store.

Markets

The same logic runs in production on OLX.pl. The other OLX markets on the same Partner API (olx.ro, olx.pt, olx.bg, olx.ua, olx.kz and olx.uz) are supported by the Copy to clipboardmarket option and not yet verified in production. Reports are welcome.

Development

1234
npm install
npm test
npm run typecheck
npm run build

Copy to clipboardnpm test covers the matching, the parsers, alerts, the three planners, the publish validation, the apply loops with their exactly-once rules, the SQL of the atomic claims, the client's answer handling, the write barrier, the encryption and the whole demo story. What the plugin relies on from the OLX documentation is in docs/olx-api-notes.md. To try the plugin in a Medusa app, run Copy to clipboardnpx medusa plugin:publish here, then Copy to clipboardnpx medusa plugin:add @koda-plus/medusa-plugin-olx in the app.

Commercial support

Built and maintained by Koda Plus, a Medusa agency from Poland. The same OLX logic runs in production for a tyre and wheel retailer with about 1 900 live OLX adverts, next to our Allegro, BaseLinker and InPost integrations. Need a custom integration or a Medusa store? Write to kontakt@koda.plus.

Trademarks

OLX and the OLX logo are trademarks of their owner, used here only to identify the marketplace this plugin connects to. This is an independent integration built on the public OLX Partner API, not affiliated with or endorsed by OLX.

License

MIT, see LICENSE.

Changelog

0.2.1 (2026-10-07)

References: stores that start soon on Medusa can be listed with Copy to clipboardsoon: true (a Soon badge, no link, Copy to clipboardurl optional); the since date is no longer shown, and an old Copy to clipboardsince in the options is ignored.

0.2.0 (2026-10-06)

Alerts: live on OLX while sold out or unpublished in Medusa, in stock but not live, in stock and never on OLX. Counters, filters, search and the product widget.
Advert lifecycle writer: deactivate, finish and reactivate by stock and product status, plan first, dry run, cap, quarantine, mass guard, reactivation of its own pauses only.
Price writer: advert prices from the Medusa base price, the whole advert sent back with only the price changed, approval above Copy to clipboardmaxPriceChangePercent.
Publishing: one advert per variant from mapped categories, required attributes read from OLX and validated before sending, exactly once (unique row, claim, lookup by Copy to clipboardexternal_id, unknown state).
Writers have two switches (option and admin toggle with who and when), separate for demo and live.
Statistics (views, phone views, observers) per advert and in totals; message threads with unread counts.
Setup guide view with live step states, checklist and troubleshooting; Copy to clipboardreferences option shown as "Running in production".
Write barrier extended from read-only to three narrow writes; IP block detection with a 30 minute pause; Copy to clipboardRetry-After on 429.
Demo mode simulates the whole story: alerts, statistics, threads, all three writers and a publish plan with one product missing a required attribute.
New tables (one migration): alerts, plan rows, publications, writer runs, threads, state; statistics and category columns on the advert snapshot.

0.1.0 (2026-10-04)

First public release, extracted from the OLX integration Koda Plus runs in production since September 2026: OAuth 2.0 connection with encrypted tokens, hourly read-only sync through the OLX Partner API v2, SKU matching by Copy to clipboardexternal_id and description, the complete-read rule, the admin page and product widget in English and Polish, the store route for "Also on OLX" links and demo mode.