Junkie on your own website
Got your own site? Show your Junkie listings on it with one copy and paste. Building something bigger? Use the API to read your listings and mark things sold from your own systems.
Website widgets
Free for every seller, no key needed. Widgets only ever show what anyone could already see on junkie.nz, and every listing links back to Junkie so buyers pay safely with buyer protection.
Your shop name in the code is the end of your shop's web address: junkie.nz/shop/your-shop. The easiest way is to copy it ready-made from your account.
Plain widget (uses your CSS)
<div data-junkie-shop="your-shop"></div> <script src="https://junkie.nz/embed.js" async></script>
It writes this HTML into the div, with no styles of its own, so you style it like the rest of your site:
<div class="junkie-listings">
<p class="junkie-listings__header"><a class="junkie-listings__shop">Your Shop</a></p>
<ul class="junkie-listings__grid">
<li class="junkie-listing"> <!-- also junkie-listing--sold, junkie-listing--reserved -->
<a class="junkie-listing__link" href="https://junkie.nz/listing/..." target="_blank">
<img class="junkie-listing__photo">
<span class="junkie-listing__title">Crown Lynn swan</span>
<span class="junkie-listing__price">$45</span>
<span class="junkie-listing__meta">1960s · Crown Lynn</span>
</a>
</li>
</ul>
<p class="junkie-listings__footer"><a class="junkie-listings__more">See everything on Junkie</a></p>
</div>A starting point for your stylesheet:
.junkie-listings__grid { list-style: none; padding: 0; display: grid; grid-template-columns: repeat(auto-fill, minmax(180px, 1fr)); gap: 1rem; }
.junkie-listing__link { display: flex; flex-direction: column; gap: .25rem; color: inherit; text-decoration: none; }
.junkie-listing__photo { width: 100%; aspect-ratio: 1; object-fit: cover; border-radius: 8px; }
.junkie-listing__price { font-weight: 600; }Want your own markup? Put a template inside the div and mark the spots with data-junkie-field. Fields: title, price, photo, url, era, maker, location, status, description.
<div data-junkie-shop="your-shop">
<template>
<article class="product">
<a data-junkie-field="url"><img data-junkie-field="photo"></a>
<h3 data-junkie-field="title"></h3>
<p class="product__price" data-junkie-field="price"></p>
</article>
</template>
</div>
<script src="https://junkie.nz/embed.js" async></script>| Attribute | What it does |
|---|---|
| data-junkie-shop | Your shop name (required) |
| data-junkie-limit | How many listings, 1 to 48. Default 12 |
| data-junkie-sold | "true" to include recently sold |
| data-junkie-header | "false" hides your shop name |
| data-junkie-mode | "iframe" for the styled version |
| data-junkie-columns | Styled only: 1 to 4. Default 3 |
| data-junkie-theme | Styled only: "light" or "dark" |
The widget fires a junkie:loaded event on the div (detail holds the data) and junkie:error if something goes wrong. Added the div after the page loaded? Call JunkieEmbed.scan().
Styled iframe
With the script, the frame grows to fit your listings:
<div data-junkie-shop="your-shop" data-junkie-mode="iframe" data-junkie-columns="3"></div> <script src="https://junkie.nz/embed.js" async></script>
Without any script, set a height yourself:
<iframe src="https://junkie.nz/embed/shop/your-shop?limit=12&columns=3&theme=light"
title="Listings on Junkie" width="100%" height="640" style="border:0" loading="lazy"></iframe>Query options: limit, columns (1 to 4), theme (light or dark), sold=1, header=0.
API
A JSON API over HTTPS at https://junkie.nz/api/v1. Version 2026-11-04, sent back in the X-Junkie-Api-Version header. We add fields without notice but never remove or rename one inside v1. The full description is at /api/v1/openapi for Postman, Insomnia or code generators.
curl https://junkie.nz/api/v1/listings?status=active \ -H "Authorization: Bearer $JUNKIE_API_KEY"
{
"data": [
{ "id": "6b1f...", "url": "https://junkie.nz/listing/6b1f...", "title": "Crown Lynn swan",
"price_nzd": 45, "price_display": "$45", "status": "active", "era": "1960s",
"maker": "Crown Lynn", "photos": ["https://..."], "updated_at": "2026-11-04T01:02:03Z" }
],
"pagination": { "limit": 25, "offset": 0, "total": 1, "next_offset": null }
}Mark something sold when it goes in your own shop:
curl -X PATCH https://junkie.nz/api/v1/listings/6b1f... \
-H "Authorization: Bearer $JUNKIE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"status":"sold"}'Keys and scopes
Make keys in your account. A key looks like jk_live_ab12cd34_… and is shown once. Send it as Authorization: Bearer (or an X-Api-Key header). Each key only ever sees its owner's listings, and only does what its scopes allow:
| Scope | Allows |
|---|---|
| listings:read | List and read your listings, including drafts and sold. |
| listings:write | Change price, title, description and status (sold, reserved, unlisted). |
| shop:read | Read your shop name, links and details. |
Keys can expire after 30, 90 or 365 days. Revoking a key stops it on the very next request. You can have 10 live keys.
Endpoints
| Method | Path | Scope | What |
|---|---|---|---|
| GET | /api/v1/me | any | Who the key belongs to, its scopes and your shop |
| GET | /api/v1/listings | listings:read | Your listings. ?status=active,sold&updated_since=&limit=&offset= |
| GET | /api/v1/listings/{id} | listings:read | One of your listings |
| PATCH | /api/v1/listings/{id} | listings:write | Change title, description, price_nzd or status |
| GET | /api/v1/shop | shop:read | Your shop details and live listing count |
| GET | /api/embed/{shop} | none | Public feed the widget uses. Live listings only, CORS open |
| GET | /api/v1/openapi | none | OpenAPI 3 description of the API |
The API can't publish drafts, change photos or touch orders. Those stay on the website where our moderation and photo checks run. Status moves allowed: active to reserved, sold or archived; reserved to active, sold or archived; sold or archived back to active.
Rate limits and errors
Each key gets 60 requests a minute. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset, plus an X-Request-Id to quote if you need help. Need more? Email hello@junkie.nz.
{ "error": { "code": "rate_limited", "message": "Slow down: this key allows 60 requests a minute.", "request_id": null } }| Status | Code | Meaning |
|---|---|---|
| 400 | invalid_request | Something in the request isn't right. The message says what. |
| 401 | missing_key, invalid_key, revoked_key, expired_key | No key, or one that doesn't work any more. |
| 403 | insufficient_scope, account_suspended | The key can't do that, or the account is on hold. |
| 404 | not_found | Doesn't exist, or isn't yours. |
| 429 | rate_limited | Too many requests. Wait for Retry-After seconds. |
| 500 | server_error | Our fault. Try again, and quote the request id if it keeps happening. |
Security
- We store a SHA-256 fingerprint of each key, never the key itself, so even we can't read it back.
- Keep keys on your server. The API doesn't answer browser (CORS) requests, so a key can't be used from a web page by accident.
- Every call is logged against its key for 90 days. Key changes and anything the API edits go in our tamper-evident audit log.
- Think a key has leaked? Revoke it in your account. It stops working straight away.
- Found a security problem? Email safety@junkie.nz.
