Junkie, vintage marketplace
Sell
For sellers and developers

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.

Plain
Plain HTML in your page. Your site's fonts and colours take over.
Styled
Junkie's look in a frame that sizes itself. Nothing can clash.
Iframe only
No script, for site builders that block scripts.

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>
AttributeWhat it does
data-junkie-shopYour shop name (required)
data-junkie-limitHow 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-columnsStyled only: 1 to 4. Default 3
data-junkie-themeStyled 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:

ScopeAllows
listings:readList and read your listings, including drafts and sold.
listings:writeChange price, title, description and status (sold, reserved, unlisted).
shop:readRead 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

MethodPathScopeWhat
GET/api/v1/meanyWho the key belongs to, its scopes and your shop
GET/api/v1/listingslistings:readYour listings. ?status=active,sold&updated_since=&limit=&offset=
GET/api/v1/listings/{id}listings:readOne of your listings
PATCH/api/v1/listings/{id}listings:writeChange title, description, price_nzd or status
GET/api/v1/shopshop:readYour shop details and live listing count
GET/api/embed/{shop}nonePublic feed the widget uses. Live listings only, CORS open
GET/api/v1/openapinoneOpenAPI 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 } }
StatusCodeMeaning
400invalid_requestSomething in the request isn't right. The message says what.
401missing_key, invalid_key, revoked_key, expired_keyNo key, or one that doesn't work any more.
403insufficient_scope, account_suspendedThe key can't do that, or the account is on hold.
404not_foundDoesn't exist, or isn't yours.
429rate_limitedToo many requests. Wait for Retry-After seconds.
500server_errorOur 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.