Retailer API

Create an API keyOpenAPI 3 specApply for an account

Basics

• Base URL https://zjdu.com/api/v1 · JSON in and out · UTF-8.
• Authentication: Authorization: Bearer zjdu_… (or X-API-Key). Up to 5 keys per account; revoke one any time.
• Prices are in USD and are exactly the trade prices your account sees on zjdu.com. A variant without a price is “price on request” (use the product’s price range). Customization is always quoted separately.
• Limits: 600 requests / minute per key; 100 quote or memorial requests / hour; 100 orders / hour; 300 uploads / hour. Over the limit you get 429 with Retry-After.
• Errors: {"error": "…", "details": ["items[0]: …"]} with 400 (bad JSON), 401 (key), 403 (account not approved), 404, 422 (validation — nothing was saved), 429.
• Idempotency: send your own order number as client_ref; repeating it returns the existing request or order instead of creating a duplicate.
• Countries are always 2-letter ISO 3166-1 codes — CN, US, DE — in requests and responses.
• Availability: products carry stock_status (in_stock, made_to_order, out_of_stock) and lead_time_days where our team has set them; null means ask us (general guidance is in availability.general).

Endpoints

Catalogue & prices

curl "https://zjdu.com/api/v1/products?category=3003&per_page=100&page=1" -H "Authorization: Bearer $ZJDU_KEY"
curl "https://zjdu.com/api/v1/products/FS-1601757508343" -H "Authorization: Bearer $ZJDU_KEY"

A product returns options (e.g. Color, Ring Size with swatch images), variants (one per combination, with price when it has a fixed price), quantity_tiers, price_low/price_high, MOQ, images and the description HTML. Image and description links are absolute.

Customization

GET /customization lists every allowed value. Each quote line can carry a custom object:

Upload a file first, then use its token:

curl -X POST https://zjdu.com/api/v1/files -H "Authorization: Bearer $ZJDU_KEY" -F "[email protected]"
# → {"token":"3afe12b8…","name":"logo.ai","size":48211}

Send the request (unknown values are rejected with 422 and nothing is saved):

curl -X POST https://zjdu.com/api/v1/quotes \
  -H "Authorization: Bearer $ZJDU_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "kind": "quote",
  "client_ref": "PO-10023",
  "note": "Ship with DHL",
  "items": [
    {
      "product": "FS-1601757508343",
      "variant_id": 51234,
      "custom": {
        "sizes": [{ "size": "US 7", "qty": 10 }, { "size": "US 8", "qty": 20 }],
        "logo": "laser", "logo_placement": "inside band", "logo_file": "<logo token>",
        "engraving": "Forever ♥", "font": "script",
        "engraving_place": "inside", "engraving_fill": "gold",
        "packaging": "gift"
      }
    }
  ]
}'

The answer is the full request (id, status new → replied → closed, lines with their customization, files). Poll GET /quotes/{id} or GET /quotes?status=replied.

Memorial diamonds

GET /memorial returns paths, materials, shapes, colours, carats, settings, metals, the sample guide, our commitments and the price per diamond. Then:

curl -X POST https://zjdu.com/api/v1/memorial \
  -H "Authorization: Bearer $ZJDU_KEY" -H "Content-Type: application/json" \
  -d '{
  "path": "celebrate",
  "contributors": [
    { "relation": "Me", "name": "Anna", "material": "hair" },
    { "relation": "Partner", "name": "Leo", "material": "hair" }
  ],
  "shape": "Heart", "color": "blue", "carat": 1,
  "setting": "Ring", "metal": "14K gold", "metal_color": "Rose", "ring_size": "US 6",
  "engraving": { "engraving": "A & L", "font": "script", "engraving_place": "inside" },
  "client_ref": "SHOP-5521"
}'

The response includes the listed price per diamond, the number of diamonds (earrings = 2) and how much hair, fur or ashes to collect — but please wait for our confirmation before sending any sample.

Orders & dropship

Place a firm order with your customer’s address. blind_ship ships without our branding or prices in the parcel; attach your own packing slip with packing_slip_file. client_ref is required and makes the call safe to retry. Link an earlier quote with quote_id.

curl -X POST https://zjdu.com/api/v1/orders \
  -H "Authorization: Bearer $ZJDU_KEY" -H "Content-Type: application/json" \
  -d '{
  "client_ref": "SHOP-100231",
  "ship_to": {
    "name": "Emma Clark", "line1": "12 Rose Lane", "city": "Austin",
    "state": "TX", "postal_code": "78701", "country": "US",
    "phone": "+1 512 555 0100", "email": "[email protected]"
  },
  "shipping_method": "express",
  "blind_ship": true,
  "packing_slip_file": "<token of your packing slip PDF>",
  "items": [
    { "product": "FS-1601757508343", "variant_id": 51234, "qty": 1,
      "custom": { "engraving": "E ♥ J", "font": "script", "engraving_place": "inside" } }
  ]
}'

• Status: received → confirmed → in_production → shipped → delivered (or cancelled).
• On confirmation our team sets amount (with amount_note for terms) — it is confirmed by people, never calculated by the API.
• Shipments appear under shipments with carrier, tracking number and tracking link; events keeps the full history.
• Cancel with POST /orders/{id}/cancel while the order is received or confirmed. Poll changes with GET /orders?updated_since=2026-10-07T00:00:00Z — or use webhooks.

Webhooks

Register an HTTPS endpoint (up to 5). Events: order.created, order.status_changed, order.updated (amount), order.shipped, quote.status_changed — or * for all.

curl -X POST https://zjdu.com/api/v1/webhooks -H "Authorization: Bearer $ZJDU_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://shop.example.com/zjdu-hook","events":["order.status_changed","order.shipped"]}'
# → {"id":3,"secret":"whsec_…"}   (shown once)

Each delivery is a JSON POST of {"event", "created_at", "data"} (data = the full order or request) with headers X-ZJDU-Event, X-ZJDU-Delivery, X-ZJDU-Timestamp and X-ZJDU-Signature. Answer with any 2xx within 10 seconds; otherwise we retry after 1 min, 5 min, 30 min, 2 h, 6 h and 12 h. Deliveries can arrive more than once — de-duplicate on X-ZJDU-Delivery.

// Node.js — verify a delivery
import crypto from "node:crypto";
function verify(rawBody, headers, secret) {
  const ts = headers["x-zjdu-timestamp"];
  const want = "v1=" + crypto.createHmac("sha256", secret).update(ts + "." + rawBody).digest("hex");
  const ok = crypto.timingSafeEqual(Buffer.from(want), Buffer.from(headers["x-zjdu-signature"] || ""));
  return ok && Math.abs(Date.now() / 1000 - Number(ts)) < 300; // reject replays older than 5 min
}

Gold, silver & exchange rate

GET /market — the same figures as our home page, from xaus.com, refreshed every 6 hours. Silver per gram is converted from USD/oz (÷ 31.1034768) and CNY uses the xaus USD/CNY rate.

{
  "quote": {
    "gold_usd_oz": 4169.1001, "gold_usd_g": 134.0397, "gold_cny_g": 900.0049,
    "silver_usd_oz": 61.512, "silver_usd_g": 1.977657, "silver_cny_g": 13.278909,
    "usd_cny": 6.714466,
    "as_of": "2026-10-06T23:54:07Z", "fetched_at": "2026-10-06T23:54:07Z",
    "price_source": "gold-api.com", "fx_source": "open.er-api.com"
  },
  "converted": ["silver_usd_g", "silver_cny_g"],
  "method": "silver per gram = USD per troy oz ÷ 31.1034768; CNY = USD × xaus USD/CNY rate",
  "source": "xaus.com", "source_url": "https://xaus.com/"
}

Questions or a platform integration (Shopify, WooCommerce, ERP)? Write to [email protected].