API reference 2026-07

The Partner API follows Shopify's Admin REST conventions closely — same resource envelopes, same cursor-based pagination, same leaky-bucket rate limiting. If you have integrated with Shopify before, the main change is the host and the auth header name.

Every request goes to https://api.slabdynasty.com and carries an API key. Keys are issued from the Developers tab of an approved seller account.

export SLAB_API_KEY="slab_live_..."   # the token shown once at creation

curl https://api.slabdynasty.com/2026-07/ping \
  -H "X-SlabDynasty-Access-Token: $SLAB_API_KEY"

Reading this with a tool instead of a browser? The whole reference is also published as an OpenAPI 3.1 spec and as a single Markdown document (llms.txt) — both generated from the same source as this page, so they cannot drift from it.

Pass your key in either header. The X-SlabDynasty-Access-Token form mirrors Shopify's X-Shopify-Access-Token, so ported client code needs only a header rename.

X-SlabDynasty-Access-Token: slab_live_...

# or, equivalently
Authorization: Bearer slab_live_...

Credentials are never accepted in the query string — a request carrying ?access_token= is rejected with a 401 before anything else happens, because URLs end up in logs, proxies and browser history.

Keys are minted per environment and the environment is baked into the token (slab_live_… / slab_test_…). Responses carry X-SlabDynasty-Api-Mode so you can assert which one you are talking to.

Test mode is read-only on production. Write endpoints reject test-mode keys with 403 test_mode_forbidden; run writes against the sandbox deployment instead. Test-mode reads return only isTest records rather than live data — that isolation is enforced at the query layer, not by filtering after the fact.

Versions are dated calendar quarters in the path, as in https://api.slabdynasty.com/2026-07/…. The scheme is Shopify's and Stripe's, and it is chosen over a /v1/-style counter for one reason: a date tells you how old a version is and therefore how long it has left, where a number tells you neither.

Pin a version explicitly in every request. There is no “latest” alias and there will not be one — an unpinned integration is one that changes behaviour on a date nobody chose. An unrecognised version returns 404 with the supported list, each entry carrying its status and sunset date, in the body.

Every version is supported for at least 12 months from its release. Once a version is deprecated its responses carry Sunset (RFC 8594) and Deprecation (RFC 9745) headers, plus a Link; rel="sunset" pointing at that version's docs — so you find out from your own logs rather than from an outage.

You are reading 2026-07 — The version to pin for new integrations. Fully supported and will not change incompatibly. See what changed in each release.

A leaky bucket per credential: 40 requests of burst capacity refilling at 2 per second in live mode, and 20 / 1 in test mode. Every response carries X-SlabDynasty-Api-Call-Limit: used/capacity in the same shape Shopify uses, so existing backoff logic ports directly.

Exceeding it returns 429 with a Retry-After header. Honour it rather than retrying immediately — the bucket is charged before the scope check, so a hot retry loop keeps itself throttled.

Collections page with keyset cursors carried entirely in the Link response header — there is no offset paging and no paging fields in the body. Walk a collection by following rel="next" until it stops appearing:

curl -sD headers.txt "https://api.slabdynasty.com/2026-07/listings.json?limit=50" \
  -H "X-SlabDynasty-Access-Token: $SLAB_API_KEY"

# headers.txt now contains:
#   Link: <https://api.slabdynasty.com/2026-07/listings.json?limit=50&page_info=eyJ...>; rel="next"
# Request that URL verbatim for the next page.
# No Link header means you have the last page.

Send page_info exactly as issued — changing a filter mid-walk is rejected with 400 page_info_filter_mismatch rather than silently skipping rows, and changing the sort with 400 page_info_sort_mismatch. Cursors expire with the data they point at, so restart from page one rather than storing them long-term.

A key carries an explicit scope list chosen when it is created, and each endpoint names the scope it requires. A write_ scope implies its read_ counterpart, matching Shopify's semantics. Calls missing the required scope return 403 insufficient_scope.

read_listings

View listings.See your listings, prices and status.

write_listings

Manage listings.Create, edit, end and relist. Can reprice or end every listing you have.

read_inventory

View inventory.See your cards and their availability.

write_inventory

Manage inventory.Mark cards available or unavailable. Can deactivate every listing you have.

read_orders

View orders.See buyer orders, including partially redacted shipping details.

write_orders

Manage orders.Cancel orders and request buyer cancellations.

read_fulfillments

View shipments.See shipping status and tracking for your orders.

write_fulfillments

Manage shipments.Mark orders shipped to our hub, attach tracking and buy labels.

read_catalog

Look up cards.Look up PSA certs, card metadata and price recommendations.

read_seller

View seller status.See your seller tier, limits, fees and payout status.

Error envelopes match Shopify's two shapes — a bare string for auth and not-found failures, a field map for validation failures — plus an additive slab_error object carrying a stable machine-readable code and the request id. Branch on the code, never on the message.

{
  "errors": { "price": ["must be greater than 0"] },
  "slab_error": {
    "code": "validation_error",
    "request_id": "req_01J8ZC4Q7N2M5V8W1X3Y6Z9B0C"
  }
}

Quote the request_id when contacting support — it identifies the exact request in our logs.

Separately from those envelopes, an individual record can come back in degraded form, carrying only its id and a slab_serialization_error. That is a 200, and it is deliberate: the rest of the response is complete. Rather than fail a whole page because one stored record is malformed — which would also block every later page, since the cursor cannot advance past it — we return the record's id and mark it. Skip those records, keep processing the rest, and send us the id. It is always our defect, never something your request can cause.

Every code the API can emit:

401invalid_api_key

The token is missing, malformed, revoked, expired, or was sent in the query string. Every authentication failure returns this one code — distinguishing them would let a caller probe which keys exist. Send the key in X-SlabDynasty-Access-Token or Authorization: Bearer. If it was working yesterday, check whether it was rotated or revoked in the dashboard.

403insufficient_scope

The key is valid but was not granted the scope this endpoint requires. Edit the key's scopes in the dashboard, or create a key with the required scope. The required scope is listed on each endpoint in the reference.

403test_mode_forbidden

A test-mode key called a write endpoint on production, where test mode is read-only. Use a live key for writes, or run the write against the sandbox deployment, where test keys can write.

403seller_not_approved

The seller account behind the key has not completed approval, so it cannot transact yet. Finish seller onboarding at slabdynasty.com/profile/settings/seller-setup.

403seller_frozen

The seller account behind the key is temporarily frozen. Contact support with the request_id.

403seller_banned

The seller account behind the key is not permitted to use the Partner API. Contact support.

403seller_not_found

The account behind this API key no longer exists. Create a key from an active seller account.

403seller_not_eligible

The seller account behind the key cannot use the Partner API right now. Contact support with the request_id.

403seller_paused

Partner API access for this seller account is temporarily paused by Slab Dynasty. Keys are intact and access resumes automatically when the pause is lifted. Pause and retry with backoff, or contact support with the request_id. Do not rotate or re-create keys — they are not the problem.

404not_found

No such resource. A resource belonging to another seller returns the same 404 as one that does not exist. Check the id. Ids come from list endpoints and are opaque strings.

404unknown_api_version

The version segment in the path is not a supported API version. The response body lists every supported version with its status and sunset date. Pin a version from slab_error.supported_versions.

400invalid_page_info

The page_info cursor is malformed or was not issued by this API. Send the cursor exactly as it appeared in the previous response's Link header. Never construct or edit one.

400page_info_sort_mismatch

The page_info cursor was issued under a different sort order. Restart the walk from page one after changing the sort.

400page_info_resource_mismatch

The page_info cursor was issued by a different endpoint. Cursors are only valid on the endpoint that issued them. Walk each collection with its own cursors from its own Link headers.

400page_info_filter_mismatch

A filter changed mid-walk. Cursors embed a hash of the filter set, so changing a filter between pages is rejected rather than silently skipping rows. slab_error.changed_params names the offending parameters. Restart the walk from page one after changing any filter.

422validation_error

One or more field values are invalid. The errors object is keyed by field, matching Shopify's 422 shape. Fix the named fields and retry.

422invalid_json

The request body is not valid JSON. Send a JSON body and a matching Content-Type.

413body_too_large

The request body exceeds the limit. slab_error.max_bytes carries the exact cap. Split the request. No documented endpoint needs a body near the cap.

403listing_write_forbidden

The seller account cannot perform this listing write right now — paused, frozen, restricted, capped, or the card is blocklisted. The message carries the specific rule. Resolve the named account issue in the dashboard, or contact support with the request_id.

409listing_write_conflict

The write conflicts with current marketplace state: the card is already actively listed, reserved by a pending order, or the listing has sold. Re-read the resource (inventory_levels.json shows why a card is unavailable) and retry against current state.

422card_not_listable

The card itself cannot be listed — sold, archived, shipped, in a trade, or awaiting submission review. slab_error.reason carries the same reason code inventory_levels.json publishes. Check the card's inventory_level for the reason. Most states resolve on their own; archived cards can be unarchived in the dashboard.

422cert_not_found

No grader recognizes this cert number (with grader omitted, PSA, BGS, SGC and CGC were all tried). The card was not created and nothing was listed. Retry with card details plus grader and images to list it from your own details, pending admin review. Check the cert number, and send grader if you know it. Newly graded slabs can take time to appear in the grader's database; you can also add the card with full details in the dashboard.

503cert_lookup_unavailable

The grader's lookup service is temporarily at capacity or unreachable, so the cert could not be verified. Nothing was created. Retry later, or resend with card details plus grader and images to list from your own details, pending admin review. Honor Retry-After and retry the same request (reuse the Idempotency-Key).

409idempotency_key_reuse

The Idempotency-Key was already used with a DIFFERENT request payload. Keys pin one request's outcome; reusing one for different work is a client bug. Generate a fresh key per logical request. Reuse a key only to retry the identical request.

409idempotency_request_in_flight

A request with this Idempotency-Key is still executing. The retry arrived before the first attempt finished. Wait Retry-After seconds and retry with the SAME key to receive the stored outcome.

429rate_limited

The leaky bucket for this credential is full. The bucket is charged before anything else, so hot retry loops keep themselves throttled. Wait Retry-After seconds. Watch X-SlabDynasty-Api-Call-Limit and slow down as used/capacity approaches 1.

503partner_api_writes_disabled

Write endpoints are temporarily disabled while Slab Dynasty resolves an incident. Read endpoints are unaffected. Honor Retry-After and retry the write later. Keep reads flowing normally.

503partner_api_disabled

The Partner API is temporarily unavailable while Slab Dynasty resolves an incident. Nothing is wrong with your key or your request. Honor Retry-After and retry with backoff. Follow status updates from support.

500internal_error

Something failed on our side. The response never carries internal detail — the request_id is the support handle. Retry with backoff. If it persists, contact support and quote slab_error.request_id.

Instead of polling, register an HTTPS endpoint under Profile → Developers → Webhooks and we'll POST you a signed JSON snapshot when something you subscribe to happens. The payload is the same resource the corresponding GET returns — one deserializer covers both — sent bare, with the topic in a header.

Topics

products/create

A listing went up — created through the API, the dashboard, or an import. Payload is the product resource as GET /products/{id}.json returns it.

products/update

A listing changed: price, title, description, offer settings, reactivation, or a status change you didn't make yourself (expiry, admin review). Also fires when a listing sells — status becomes archived with slab_unavailable_reason: "sold".

products/delete

A listing was taken off the marketplace (soft deactivation — the same thing DELETE /products/{id}.json does). The payload still serializes the full resource so you can see its final state.

orders/create

A buyer bought one of your cards — marketplace checkout, accepted offer, or any other sale path. Payload is the order resource as GET /orders/{id}.json returns it.

orders/updated

An order's lifecycle moved: shipped to the hub, authenticated, shipped to the buyer, delivered, refunded, payout released. Fires on every status transition, so consume it idempotently.

orders/cancelled

An order was cancelled or failed — buyer cancellation, admin cancellation, or payment failure. cancelled_at is set and financial_status reflects the refund state.

Request headers

X-SlabDynasty-Webhook-Signature

t=<unix-seconds>,v1=<hex> — HMAC-SHA256 of "t.rawBody" with your endpoint's signing secret. Verify EVERY request.

X-SlabDynasty-Webhook-Topic

The topic, e.g. orders/create.

X-SlabDynasty-Webhook-Id

The event id (evt_…). Stable across retries — deduplicate on it, because a slow 2xx can race a retry.

X-SlabDynasty-Webhook-Attempt

1-based attempt counter, up to 8.

X-SlabDynasty-Api-Version

The API version whose serializers shaped the payload.

X-SlabDynasty-Api-Mode

live or test, matching the endpoint's environment.

X-SlabDynasty-Webhook-Test

Present ("true") only on deliveries fired from the dashboard's Send test button.

Answer with any 2xx within 10 seconds — ack first, process async. Anything else (including a timeout) is retried with backoff, up to 8 attempts over roughly a day; each retry is re-signed with a fresh timestamp. An endpoint that does nothing but fail is automatically disabled, and one click in the dashboard re-enables it. Every delivery, every attempt and every response code is visible in the dashboard's webhook log, which can also redeliver any event on demand.

The signing secret (slab_whsec_…) is per endpoint, revealed in the dashboard whenever you need it, and rotatable in one click — rotation takes effect on the next delivery. Verification is ~15 lines:

import crypto from "node:crypto";
import express from "express";

const app = express();

function verifySlabDynastyWebhook(rawBody, signatureHeader, secret) {
  // Header shape: "t=<unix-seconds>,v1=<hex>"
  const params = new Map(
    signatureHeader.split(",").map((part) => {
      const i = part.indexOf("=");
      return [part.slice(0, i).trim(), part.slice(i + 1).trim()];
    })
  );
  const t = params.get("t");
  const v1 = params.get("v1");
  if (!t || !v1) return false;

  // Replay guard: reject stamps older than an hour. Retries are re-signed
  // at send time, so a legitimate delivery is never near this boundary.
  if (Math.abs(Date.now() / 1000 - Number(t)) > 60 * 60) return false;

  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${t}.${rawBody}`)
    .digest("hex");
  return (
    v1.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(v1), Buffer.from(expected))
  );
}

app.post(
  "/webhooks/slabdynasty",
  // The RAW body, before any JSON parsing — the signature covers the exact
  // bytes we sent, and a re-serialized body will not match.
  express.raw({ type: "application/json" }),
  (req, res) => {
    const ok = verifySlabDynastyWebhook(
      req.body.toString("utf8"),
      req.get("X-SlabDynasty-Webhook-Signature") ?? "",
      process.env.SLAB_WEBHOOK_SECRET // from the dashboard: slab_whsec_...
    );
    if (!ok) return res.status(401).end();

    // Ack fast (any 2xx within 10s), then process asynchronously.
    res.status(200).end();

    const topic = req.get("X-SlabDynasty-Webhook-Topic");     // e.g. "orders/create"
    const eventId = req.get("X-SlabDynasty-Webhook-Id"); // dedupe on this — retries reuse it
    const resource = JSON.parse(req.body.toString("utf8"));
    // handle(topic, eventId, resource)
  }
);