Repository navigation
🎃 New adapter: PlentyONE / plentymarkets (e-commerce ERP) #1014
Description
Part of the October Challenge #997.
Why
PlentyONE (formerly plentymarkets) is one of the most widely used e-commerce ERPs among German online retailers: orders, items and variations, stock across warehouses, and customer contacts for shops and marketplaces such as Amazon, eBay and Otto. The catalog has JTL-Wawi, Xentral, weclapp and Billbee, but no plentymarkets (grep -ril plenty packages/backend/src/adapters finds nothing). With an adapter, a user could ask "which orders from yesterday are still in status 5?", "how much stock of SKU X is in the main warehouse?" or "show customer 1234's last orders".
Self-hosted vs Cloud
- Self-hosted: available in Community and Business; no edition gating.
- Cloud (
DEPLOYMENT_MODE=cloud): available. PlentyONE systems are public SaaS (https://p<PID>.my.plentysystems.com), so the SSRF guard allows them. On Cloud trial plans, installs count toward the connector limit (license-guard.service.ts:65). - Who can use it: any role except VIEWER can install it (
adapters.controller.ts:207). The username and password live encrypted in the organization's own connectorauthConfig. The cached bearer token is encrypted too and keyed by connector (docs/connectors/login-token-auth.md, "Security notes"). Nothing is shared across organizations.
What to build
packages/backend/src/adapters/de/plentymarkets.json. Start with npm run adapter:new -- plentymarkets --region de --auth LOGIN_TOKEN.
- API docs: https://developers.plentymarkets.com/en-gb/developers/main/rest-api-guides/getting-started.html (REST reference: https://developers.plentymarkets.com/en-gb/plentymarkets-rest-api/index.html; order guide: https://developers.plentymarkets.com/en-gb/developers/main/rest-api-guides/order-data.html).
- Base URL:
{{PLENTY_URL}}/rest, wherePLENTY_URLis e.g.https://p12345.my.plentysystems.com. The exact URL is shown under Setup → Settings → API → Data. - Auth:
LOGIN_TOKEN.POST {{PLENTY_URL}}/rest/loginwith{"username": "${username}", "password": "${password}"}returns{token_type, expires_in: 86400, access_token, refresh_token}. MaptokenJsonPath: "access_token",expiryJsonPath: "expires_in",expiryFormat: "ttl_seconds",refreshOn401: true, and setproactiveRefreshSecondswell below 86400 (e.g. 3600). Copy the shape fromde/hrworks.json:15-28. - Env vars:
PLENTY_URL,PLENTY_USERNAME,PLENTY_PASSWORD. Ininstructions, recommend a dedicated REST user with only the needed rights (Setup → Settings → User → Accounts). That user also counts toward the concurrent API user limit (default 3; a 429 means the limit was hit). - Rate limits depend on the plan (Basic: 80 reads/min, 40 writes/min). Put this in
instructions. - Category:
e-commerce. probe:plentymarkets_list_warehouses.
| Tool | Endpoint | Expected hints |
|---|---|---|
plentymarkets_list_orders |
GET /orders (statusFrom, statusTo, createdAtFrom, createdAtTo, contactId, with[], page, itemsPerPage) |
read-only |
plentymarkets_get_order |
GET /orders/{orderId} (with[]=orderItems, addresses) |
read-only |
plentymarkets_list_variations |
GET /items/variations (numberExact, itemName, barcode, isActive) |
read-only |
plentymarkets_list_stock |
GET /stockmanagement/stock (variationId, warehouseId) |
read-only |
plentymarkets_list_warehouses |
GET /stockmanagement/warehouses |
read-only |
plentymarkets_list_contacts |
GET /accounts/contacts (email, fullText, page) |
read-only |
plentymarkets_get_contact |
GET /accounts/contacts/{contactId} |
read-only |
plentymarkets_update_order_status |
PUT /orders/{orderId} with body {statusId} |
write, destructive, idempotent (derived from PUT). Ship it with "enabled": false so a workspace turns it on deliberately |
Hints come from the HTTP method (docs/tool-definition.md:503-545); do not hand-write annotations. Check each path and parameter against the REST reference and note any deviation in the PR.
Where to look
packages/backend/src/adapters/de/hrworks.json:15-28— a workingLOGIN_TOKENadapter (POST credentials, read token, refresh).docs/connectors/login-token-auth.md—authConfigfields (loginUrl,loginBody,tokenJsonPath,expiryJsonPath,expiryFormat).packages/backend/src/adapters/de/jtl-wawi.json— a comparable German commerce ERP; copy how itsinstructionsexplain orders vs items vs stock.packages/backend/src/adapters/intl/todoist.live.spec.ts— spec template; live calls behindRUN_PLENTYMARKETS_LIVE=1..github/CONTRIBUTING.md:136— the "Add an adapter" checklist; 🐣 Good first issue: contribute a new MCP adapter #982 — adapter guide.
Acceptance criteria
-
de/plentymarkets.jsonwith the 8 tools above; the write tool has"enabled": false. -
validate-adapters.mjs --warnis clean (the validator requiresinstructions≥ 800 chars and each tool description ≥ 60 chars,scripts/validate-adapters.mjs:32);catalog.tsis regenerated;adapter-count.mjs --checkpasses. -
de/plentymarkets.live.spec.ts: static checks (auth typeLOGIN_TOKEN,loginUrlends with/rest/login,tokenJsonPathisaccess_token, write tool disabled); withRUN_PLENTYMARKETS_LIVE=1it logs in and lists warehouses and orders on a trial system.npx jest src/adapters/de/plentymarketspasses inpackages/backend. - No password or token appears in the spec, the fixtures or the PR.
- Logo at
packages/frontend/public/logos/connectors/plentymarkets.svg. - Docs updated: optional
content/guides/en/plentymarkets-to-mcp.mdx.
Out of scope
- Creating orders, items or contacts; deleting anything; stock corrections (
/stockmanagement/.../correction). - The plugin/Ceres interface, webhooks (event procedures), marketplace-specific endpoints.
- Using
refresh_token. Re-login throughLOGIN_TOKENis enough.
Free account: PlentyONE offers a 30-day free test system without obligation (start from https://www.plentyone.com). Enable REST access for a user in it.
Size
M (1–2 days). The login flow and the order filters need testing against a real trial system.
How to claim
Comment "I'd like to work on this" and we'll assign you. Rules in #997.
Activity