Developer documentation
NEXT API
The NEXT API connects your own systems (shop, ERP, scripts) directly to Shirtking.NEXT: import products, submit orders, and fetch status, shipments, stock and invoices.
1. Quick start
- In the portal open API und Webhooks.
- Click “New API key” and pick the required permissions (scopes).
- Copy the key (starts with
skn_) right away – it is only shown once. - Send a first test call:
curl https://next.shirt-king.de/api/public/v1/products \
-H "Authorization: Bearer skn_DEIN_SCHLUESSEL"Base URL of all commands: https://next.shirt-king.de/api/public/v1. The full machine-readable spec (OpenAPI) is at /openapi.json.
2. Authentication & rules
- Auth: Every call needs the header
Authorization: Bearer skn_…. - Scopes:
read(read everything),inventory:read,orders:write(create orders),products:write(import products). - Rate limit: 120 calls per minute per key. Above that: status 429 – wait briefly and retry.
- Idempotency-Key: Required for all POST commands. Resending the same key (e.g. after a timeout) returns the first response – nothing is created twice. Tip: use your shop order number.
- Amounts: always net, in cents (1290 = €12.90).
- Lists: paginated with
?page=1&limit=50(max 100). Response:{ data: [...], meta: { page, limit, total, hasMore } }.
3. Commands (endpoints)
GET/catalogScope: read
Returns base garments with ID, colours, sizes, print methods and print areas (keys like front, back). Needed before any product import. Search with ?q=hoodie.
curl "https://next.shirt-king.de/api/public/v1/catalog?q=oversized" -H "Authorization: Bearer skn_…"POST/productsScope: products:write
Creates a finished product: downloads the artwork (public https link, PNG/SVG/PDF, max 50 MB), places it in mm from the top-left of the print area, approves the product and creates NEXT SKUs. With shopSku you link your existing shop SKU (e.g. from podOS) – orders with that SKU are recognised automatically afterwards.
curl -X POST https://next.shirt-king.de/api/public/v1/products \
-H "Authorization: Bearer skn_…" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: import-tee-001" \
-d '{
"name": "Logo Tee",
"catalogProductId": "<id aus /catalog>",
"printMethod": "dtf",
"prints": [{
"area": "front",
"artworkUrl": "https://example.com/logo.png",
"widthMm": 250, "heightMm": 180,
"offsetXMm": 25, "offsetYMm": 40
}],
"variants": [
{ "color": "Black", "size": "M", "shopSku": "PODOS-TEE-BLK-M" },
{ "color": "Black", "size": "L", "shopSku": "PODOS-TEE-BLK-L" }
]
}'Response 201 with product ID and SKUs. 422 = invalid input (e.g. colour not in catalogue), 409 = shop SKU already in use.
GET/productsScope: read
All your products with approved variants (NEXT SKU, price) and linked shop SKUs. Use it to reconcile SKUs in your shop.
Every product and variant contains images with links to the finished mockups (colour, front/back). Links are valid for 6 hours – download the images during import and host them yourself; call again for fresh links. With ?include=none no images are returned.
PATCH/products/{id}Scope: products:write
Changes product name, SKU prefix or active status. Approved SKUs stay unchanged – a new prefix applies to new versions only. If the prefix is taken you get 409 sku_prefix_taken.
curl -X PATCH https://next.shirt-king.de/api/public/v1/products/6a2fb191-… \
-H "Authorization: Bearer skn_…" \
-H "Content-Type: application/json" \
-d '{ "name": "Supporter Shirt 2026", "skuPrefix": "SUP26", "active": true }'DELETE/products/{id}/versions/{version}Scope: products:write
Discards a draft version that is not approved yet. Approved versions are immutable (409 not_draft). If the draft is the only version, the product is deleted too (productDeleted: true).
curl -X DELETE https://next.shirt-king.de/api/public/v1/products/6a2fb191-…/versions/2 \
-H "Authorization: Bearer skn_…"DELETE/products/{id}Scope: products:write
Deletes a product (response 204). If it was already ordered you get 409 product_in_use – deactivate it with PATCH { "active": false } instead.
POST/ordersScope: orders:write
Submits an order. sku may be a NEXT SKU or a linked shop SKU. country is the two-letter country code (DE, AT, CH …). The order is checked immediately and, depending on your settings, released to production automatically.
curl -X POST https://next.shirt-king.de/api/public/v1/orders \
-H "Authorization: Bearer skn_…" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: shop-10045" \
-d '{
"externalRef": "shop-10045",
"shippingAddress": {
"name": "Max Muster", "street": "Hauptstr. 1",
"postalCode": "10115", "city": "Berlin",
"country": "DE", "email": "max@example.com"
},
"items": [{ "sku": "PODOS-TEE-BLK-M", "quantity": 2 }]
}'GET/orders · /orders/{id}Scope: read
List with filters ?status=shipped and ?updated_since=2026-11-01T00:00:00Z; single lookup by ID or order number. Typical statuses: checked, clarification, in_production, shipped, cancelled.
POST/orders/{id}/cancelScope: orders:write
Cancels an order (by ID or order number) as long as it is not in production yet. Paid amounts are refunded automatically. Optional reason. Too late: 409 cancellation_not_allowed; already cancelled: meta.alreadyCancelled: true.
curl -X POST https://next.shirt-king.de/api/public/v1/orders/NX-10045/cancel \
-H "Authorization: Bearer skn_…" \
-H "Content-Type: application/json" \
-d '{ "reason": "Kunde hat storniert" }'GET/shipmentsScope: read
Shipments with carrier and tracking number – to pass on to your customers.
GET/inventoryScope: inventory:read
Current stock of your stored items.
GET/invoicesScope: read
Invoices and credit notes with number, date, amount and payment status.
4. Workflows: what to call when
A) Take over existing shop products (once)
GET /catalog→ find the matching garment, noteid, colour names, sizes and print area.POST /products→ once per shop product, with artwork and the old shop SKUs asshopSku.GET /products→ check that all variants and shop SKUs exist.
Result: nothing has to change in your shop.
B) Daily order flow
- Customer orders and pays in your shop.
POST /orderswithIdempotency-Key= shop order number.- Wait for webhook
order.shipped– or poll every 15 minutes withGET /orders?updated_since=…. GET /shipments→ write the tracking number into your shop.
C) Order stuck in “clarification”
- Webhook
order.clarificationor statusclarificationinGET /orders/{id}. - Most common cause: unknown SKU. Click “Link SKU” on the order in the portal – or import the product with
POST /productsusing thatshopSku.
D) Monthly reconciliation
GET /invoices and GET /inventory for accounting and stock overview.
5. Migrating existing shop products
This chapter is deliberately precise so a working migration script can be built from it without follow-up questions. It describes how to migrate products from an existing shop (e.g. created via podOS) into NEXT without changing anything in the shop.
Core principle
- The existing shop stays untouched. Products, texts, images, prices and URLs remain as they are.
- NEXT creates its own NEXT SKU per variant. The old shop SKU (e.g. the podOS SKU) is stored as an alias (field
shopSku). - When an order arrives with a shop SKU, NEXT looks up the exact NEXT SKU first, then the alias. Match → normal checks. No match → status
clarification(clarification) with reasonunknown_sku. - Shop SKUs are unique per account. The same shop SKU cannot be linked to two NEXT variants (error 409).
Step-by-step migration
- Create a key: In the portal under API und Webhooks create a key with scopes
readandproducts:write. - Read the catalogue:
GET /catalogand find the matching garment per shop product. Note:id(used ascatalogProductId), the exact colour names, the sizes and the print-area keys (e.g.front,back) with their dimensions in mm. - Provide artwork files: Every artwork file must be downloadable via a public https link (PNG, SVG or PDF, max 50 MB, 300 DPI recommended). Signed or expiring links are fine as long as they work at import time.
- Import products: Exactly one call of
POST /productsper product. Fields:
{
"name": "Produktname (Pflicht, frei wählbar)",
"catalogProductId":"ID aus GET /catalog (Pflicht)",
"printMethod": "dtf | dtg | flex … (Pflicht, siehe /catalog)",
"prints": [{
"area": "front | back | … (Schlüssel aus /catalog)",
"artworkUrl":"https://…/datei.png (öffentlich erreichbar)",
"widthMm": 250, // Druckbreite in mm
"heightMm": 180, // Druckhöhe in mm
"offsetXMm": 25, // Abstand von links, in mm
"offsetYMm": 40 // Abstand von oben, in mm
}],
"variants": [
{ "color": "Black", "size": "M", "shopSku": "PODOS-TEE-BLK-M" }
// color/size müssen exakt zu /catalog passen
// shopSku optional, aber für Migration entscheidend
]
}- Idempotency-Key: Set a stable key per product, e.g.
mig-<shop-produkt-id>. On timeout simply repeat the same call – no duplicate is created. - Check the response: 201 = product created, approved, SKUs and aliases created. 422 = invalid input (the message names the field, e.g. unknown colour). 409 = a
shopSkuis already taken – that variant already exists, do not recreate the product. - Reconcile:
GET /productsand verify every shop product has exactly one NEXT product with all variants and shop SKUs. - Test order:
POST /orderswith an old shop SKU. Expected result: statuschecked(notclarification).
Rules a script must follow
- Never send two products with the same
shopSku– SKU mapping is unique per account. - Colour and size names exactly as in
GET /catalog(mind letter case). - Placement is always in mm from the top-left corner of the print area; width + offset must not exceed the area width.
- On 429 (rate limit) wait briefly and retry; on 5xx retry with growing gaps; on 422 fix the payload, do not retry as-is.
- Variants that do not exist in the shop (e.g. only some sizes) are simply omitted – do not send empty values.
Reference script (Python)
Reads a CSV file produkte.csv with columns name, catalog_product_id, print_method, area, artwork_url, width_mm, height_mm, offset_x_mm, offset_y_mm, color, size, shop_sku and imports all products:
import csv, json, time, urllib.request
BASE = "https://next.shirt-king.de/api/public/v1"
KEY = "skn_DEIN_SCHLUESSEL"
def call(method, path, body=None, idem=None):
req = urllib.request.Request(
BASE + path, method=method,
data=json.dumps(body).encode() if body else None,
headers={"Authorization": f"Bearer {KEY}",
"Content-Type": "application/json",
**({"Idempotency-Key": idem} if idem else {})})
try:
with urllib.request.urlopen(req) as r:
return r.status, json.loads(r.read())
except urllib.error.HTTPError as e:
return e.code, json.loads(e.read())
# Zeilen nach Produkt gruppieren (gleicher name = ein Produkt)
products = {}
for row in csv.DictReader(open("produkte.csv")):
p = products.setdefault(row["name"], {
"name": row["name"],
"catalogProductId": row["catalog_product_id"],
"printMethod": row["print_method"],
"prints": [{
"area": row["area"],
"artworkUrl": row["artwork_url"],
"widthMm": int(row["width_mm"]),
"heightMm": int(row["height_mm"]),
"offsetXMm": int(row["offset_x_mm"]),
"offsetYMm": int(row["offset_y_mm"]),
}],
"variants": [],
})
p["variants"].append({"color": row["color"],
"size": row["size"],
"shopSku": row["shop_sku"]})
for name, body in products.items():
idem = "mig-" + name.lower().replace(" ", "-")
while True:
status, res = call("POST", "/products", body, idem)
if status == 201:
print("OK:", name, "→", res["id"]); break
if status == 429:
time.sleep(5); continue
if status == 409:
print("Shop-SKU schon verknüpft:", name, res); break
raise SystemExit(f"Fehler {status} bei {name}: {res}")
# Abgleich: alles angelegt?
status, res = call("GET", "/products?limit=100")
print("Produkte in NEXT:", res["meta"]["total"])Afterwards: ongoing operation
New orders from the shop go via POST /orders with the old shop SKUs and are recognised automatically. If an order still reports clarification/unknown_sku, an alias is missing: click “Link SKU” on the order in the portal or re-import the variant via POST /products .
6. Webhooks
In API und Webhooks add an https URL. NEXT sends events as POST:
order.created, order.accepted, order.clarification, order.in_production, order.shipped, order.cancelled, inventory.low, inventory.updated, invoice.created, complaint.updated
{ "id": "evt_…", "type": "order.shipped", "createdAt": "2026-11-07T10:00:00Z", "data": { … } }Verify the signature header x-shirtking-signature: t=<unix>,v1=<hex>: v1 = HMAC-SHA256(your secret, `${t}.${body}`). Respond with 2xx; otherwise delivery is retried up to 8 times with growing gaps (2, 4, 8 … min).
// Node.js
import crypto from "node:crypto";
const [t, v1] = header.split(",").map((p) => p.split("=")[1]);
const ok = crypto.createHmac("sha256", SECRET).update(`${t}.${rawBody}`).digest("hex") === v1;7. Errors & tips
Errors always come as { "error": { "code", "message" } }.
- 401 key missing/invalid · 403 scope missing · 404 not found
- 409 conflict (e.g. idempotency key with different body, shop SKU taken)
- 422 invalid input – the message names the field · 429 too many calls
Questions? Contact us via the Helpdesk.