WSL Wholesale API

01 Overview

The WSL API is how your systems talk to our warehouse directly, with no spreadsheets and no FTP.

Every call is authenticated, returns JSON, and runs over HTTPS. There is no public surface: you see only the products, stock, and orders tied to your own account. Four things you can do:

Versioning

The version is in the path (/api/wsl/v1). We add to v1 without breaking it: new fields and new values may appear, so ignore what you don't recognise. The 2 October 2026 release was a one-off exception, made from integrator feedback while the API was new; the changes that may need code changes are marked in the Change log. Anything else that would break an integration comes with a new version.

02 Authentication

One key, sent as a bearer token, identifies you on every request.

Put your key in the Authorization header:

Authorization: Bearer wsl_live_9f2c…

Keys are environment-prefixed so a leak is obvious in a log:

Identity comes only from the key, never from anything else in the request. Any account or order id you send is ignored; you can only ever reach your own data.

What a failed auth looks like

03 Conventions

A handful of rules hold across every endpoint.

Errors always take this shape. The field is named, the value never echoed back:

{
  "error": "insufficient_stock",
  "message": "Line 2: only 3 available.",
  "correlationId": "7b1f…"
}

Field types

Every field in this guide is one of these. Watch the string-vs-number and the money types especially:

A field marked nullable may be null or absent; required must be sent. correlationId is on every response, and the list endpoints (/products, /orders) also carry page, pageSize, and hasMore, not repeated in the tables below.

04 Catalogue & stock

Read the products you're entitled to, then check what's on the shelf.

Confirms your key works, tells you how many products you're entitled to, and gives you your limits. A good first call.

{
  "retailer": "Acme Ltd",
  "environment": "test",
  "entitledProductCount": 42,
  "discontinuedProductCount": 3,
  "serverTimeUtc": "2026-09-03T02:10:00Z",
  "pagination": { "defaultPageSize": 50, "maxPageSize": 200, "totalPagesAtDefault": 1, "totalPagesAt25": 2 },
  "limits": { "requestsPerMinute": 60, "requestsPerDay": 10000, "ordersPerDay": 500, "maxSkusPerRequest": 200 },
  "correlationId": "…"
}

Your entitled catalogue, paged, including discontinued products (flagged). Wholesale prices are ex-GST; RRPs include GST.

{
  "items": [ {
    "sku": "10432", "status": "active", "barcode": "9421…", "title": "…", "brand": "…",
    "images": ["https://…1.webp", "https://…2.webp"], "wholesalePriceExGst": 12.34,
    "currency": "NZD", "gstIncluded": false, "rrp": 29.95, "rrpIncludesGst": true,
    "colour": "Black", "size": "M", "material": "Silicone", "flavour": "N/A",
    "width": 40, "height": 210, "depth": 35, "weight": 150,
    "category": "Rabbit Vibrators",
    "categories": [ { "master": "Sex Toys", "header": "Vibrators", "sub": "Rabbit Vibrators" },
                    { "master": "Brands", "header": "Brands", "sub": "…" } ],
    "nextExpiry": "2027-06-30T00:00:00Z", "updatedAtUtc": "2026-10-02T03:20:00Z"
  } ], "page": 1, "pageSize": 50, "hasMore": true, "correlationId": "…"
}

Each entry in items is a product:

GET /products/{sku} returns a single product (same fields), or 404 if it's unknown or not one of yours (the two are indistinguishable).

Live availability, per SKU. Deliberately lightweight so you can poll it often. Pass at least one ?sku=: repeat it, or comma-separate (?sku=10432,10433), up to 200 per call.

{
  "asAtUtc": "2026-09-03T02:11:00Z",
  "items": [ { "sku": "10432", "status": "active", "available": 25, "asAtUtc": "…" },
             { "sku": "99999", "status": "not_available", "available": null, "asAtUtc": "…" } ],
  "correlationId": "…"
}

The response carries asAtUtc and an items array, one per SKU you asked for, in your order; each item is:

What changed since…

GET /stock?changedSince=2026-10-01T09:00:00Z lists only the SKUs whose stock band has changed since then (sold out, back in, or moved band), each with its live figure. It's paged like /products (page, pageSize up to 200, hasMore), so polling it through the day keeps your stock right without re-reading everything. Use either sku or changedSince in one call, not both. It can occasionally include a SKU whose band didn't move for you; that's harmless.

05 Placing orders

Submit an order; get an immediate yes or a precise no. Nothing is half-created.

You identify the order by your own reference (clientOrderRef). That reference is the idempotency key: send it twice and you get the original order back, never a duplicate.

{
  "clientOrderRef": "PO-10021",        // your ref — required, unique per order
  "recipientName": "Jo Buyer",
  "recipientEmail": "jo@example.com",
  "recipientPhone": "021 000 0000",      // required — courier contact
  "deliveryAddress": {
    "address1": "1 Queen St", "city": "Wellington",
    "postcode": "6011", "country": "NZ"       // NZ, or AU (state required)
  },
  "lines": [ { "sku": "10432", "quantity": 2 } ],
  "dryRun": true                       // validate only, create nothing
}

Request body

deliveryAddress

lines[]

All-or-nothing validation

The order is validated as a whole. If anything is wrong, nothing is created and you get a 422 with a reason on every line, so you can fix and resubmit against the same ref:

{ "error": "validation_failed", "correlationId": "…",
  "errors": [],
  "lines": [
    { "sku": "10432", "quantity": 2, "ok": true, "reason": null, "available": 25 },
    { "sku": "99999", "quantity": 1, "ok": false, "reason": "unknown_sku", "available": null }
  ] }

On success you get 201 Created (or 200 if you're replaying a ref that already exists), with the accepted lines and their ex-GST unit prices. A test key, or "dryRun": true, creates nothing and returns the dry-run response instead: the same prices, and the payment a real order would show.

{
  "clientOrderRef": "PO-10021",
  "status": "Accepted",
  "alreadyExisted": false,
  "lines": [ { "sku": "10432", "quantity": 2, "unitPriceExGst": 12.34 } ],
  "payment": { "method": "card", "amountCharged": 43.33, "gstIncluded": 5.65, "storeCreditApplied": 0.00, "shippingExGst": 13.00, "currency": "NZD" },
  "correlationId": "…"
}

Success response

Dry-run response

A dry run (or any order on a test key) that would be accepted returns 200 with your prices and a preview of the payment, worked out exactly as a real order would be. Nothing is created, held or charged. One that wouldn't be accepted gets the same 422 as a real order.

{
  "status": "dry_run",
  "dryRun": true,
  "wouldAccept": true,
  "correlationId": "…",
  "lines": [ { "sku": "10432", "quantity": 2, "available": 25, "unitPriceExGst": 12.34 } ],
  "payment": { "method": "card", "amountCharged": 43.33, "gstIncluded": 5.65, "storeCreditApplied": 0.00, "shippingExGst": 13.00, "currency": "NZD" }
}

Rejected line (in a 422 or 409)

06 Shipping

Every order pays shipping at the same rates as the wholesale website. Which table applies depends on the delivery address, not your account.

• Delivering in New Zealand: by the order's goods value, ex-GST, before any store credit.
• Delivering to Australia: by the parcel's weight. That's the greater of its actual weight and its volumetric weight (length × width × height in mm ÷ 5,000, in grams), added up across the order from each product's weight, width, height and depth. A product with no measurements counts as 0.

All rates are NZD, ex-GST. Each band starts at its lower figure, so an order of exactly $250.00 pays $20.00.

New Zealand: by goods value (ex-GST)

Australia: by parcel weight

07 Order status & tracking

Poll your order; tracking appears once it dispatches, or have us push it to you with a webhook.

Status for one of your orders. Another retailer's ref is a 404, as is any ref on a test key, which has no orders.

{ "clientOrderRef": "PO-10021", "status": "Dispatched",
  "carrier": "NZ Post", "trackingNumber": "ABC123",
  "trackingUrl": "https://www.nzpost.co.nz/tools/tracking/item/ABC123",
  "dispatchedAtUtc": "…", "placedAtUtc": "…", "lines": […], "correlationId": "…" }

status is one of AwaitingDispatch, Dispatched, or Cancelled. Poll once or twice a day; carrier, trackingNumber, and trackingUrl fill in at dispatch.

Your orders, newest first, from the last 24 months. Filter with ?status=, ?placedSince=, ?placedBefore=; paged like /products. On a test key this list is always empty, test keys create no orders.

08 Webhooks

Rather than polling for dispatch, we can push you an event the moment an order ships.

A webhook is optional and complements polling, it doesn't replace it. When one of your orders is dispatched, we POST an order.dispatched event to a URL you give us, so you can update your store and notify your customer straight away instead of waiting for your next poll of GET /orders.

Turning it on

There's no self-service dashboard: setup is handled by us, so it stays a deliberate, verified step.

1. Stand up an HTTPS endpoint. A public URL that accepts a POST with a JSON body and returns 2xx quickly. HTTP and internal/private addresses are refused.
2. Send us the URL. Email it to your Wholesale Solutions account contact and ask to enable dispatch webhooks. We configure it against your account.
3. Store your signing secret. We give you a secret (whsec_…), shown once: keep it server-side. It's how you prove each call really came from us.
4. Verify a test event. We fire a webhook.test event at your endpoint; confirm you can validate its signature, and you're live.

What we send when an order dispatches. The body carries only your own order reference and the dispatch details, never your customer's personal data (you already hold that).

{
  "id": "evt_dispatched_9f2c…",   // stable event id — dedupe on this
  "type": "order.dispatched",
  "createdAtUtc": "2026-09-15T02:11:00Z",
  "data": {
    "clientOrderRef": "PO-10021", "status": "Dispatched",
    "carrier": "NZ Post", "trackingNumber": "ABC123",
    "trackingUrl": "https://www.nzpost.co.nz/tools/tracking/item/ABC123",
    "dispatchedAtUtc": "2026-09-15T02:10:00Z",
    "lines": [ { "sku": "10432", "quantity": 2, "unitPriceExGst": 12.34 } ]
  }
}

The data block is the same PII-free shape as GET /orders/{ref}. We also send three headers:

Verifying the signature

Every call is signed with your secret so you can be sure it's from us and hasn't been tampered with. Read t and v1 from the X-WSL-Signature header, then recompute the HMAC over the exact raw request body:

expected = HMAC_SHA256(secret, t + "." + rawBody)   // hex, lowercase

1. Compare constant-time. Check your expected equals v1 using a constant-time comparison, not ==.
2. Reject stale calls. If t is more than a few minutes old, reject it: this stops a captured request being replayed.
3. Sign the raw bytes. HMAC the body exactly as received, before any JSON re-serialisation: reformatting it changes the signature.

09 Error reference

Every error is a status code plus a stable error string you can branch on.

10 Rate limits

Generous for real use, firm against runaways. Limits are per key.

Your own numbers are in GET /ping (limits). They're set on your account and can be adjusted, so talk to us if your volumes grow. A full catalogue pull at 200 per page is under 250 calls, and a nightly updatedSince sync or a /stock?changedSince= poll is far fewer, so day-to-day use sits comfortably inside any tier.

11 Getting started

From a test key to a live order, in order.

1. Ping with your test key. Call GET /ping: a name and an entitled count back means you're connected.
2. Pull your catalogue. Page through GET /products and map SKUs, prices, and images into your system. Remember wholesale prices are ex-GST and RRPs include GST.
3. Wire up stock. Read GET /stock?sku=… for the SKUs you list, then keep it current with GET /stock?changedSince=… on the cadence that suits you. Delist anything that comes back "not_available", or "discontinued" at 0.
4. Dry-run an order. POST /orders with "dryRun": true (or just your test key). Check the prices, shipping and the payment preview it returns, and that you handle a 422.
5. Go live. Swap in your wsl_live_ key, place one real order, which on a card-paying account is charged to your saved card, and watch it move through GET /orders/{ref} to Dispatched with tracking. Prefer a push over polling? Ask us to set up a webhook.