Back to helpdesk

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

  1. In the portal open API und Webhooks.
  2. Click “New API key” and pick the required permissions (scopes).
  3. Copy the key (starts with skn_) right away – it is only shown once.
  4. 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)

  1. GET /catalog → find the matching garment, note id, colour names, sizes and print area.
  2. POST /products → once per shop product, with artwork and the old shop SKUs as shopSku.
  3. GET /products → check that all variants and shop SKUs exist.

Result: nothing has to change in your shop.

B) Daily order flow

  1. Customer orders and pays in your shop.
  2. POST /orders with Idempotency-Key = shop order number.
  3. Wait for webhook order.shipped – or poll every 15 minutes with GET /orders?updated_since=….
  4. GET /shipments → write the tracking number into your shop.

C) Order stuck in “clarification”

  1. Webhook order.clarification or status clarification in GET /orders/{id}.
  2. Most common cause: unknown SKU. Click “Link SKU” on the order in the portal – or import the product with POST /products using that shopSku .

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 reason unknown_sku.
  • Shop SKUs are unique per account. The same shop SKU cannot be linked to two NEXT variants (error 409).

Step-by-step migration

  1. Create a key: In the portal under API und Webhooks create a key with scopes read and products:write .
  2. Read the catalogue: GET /catalog and find the matching garment per shop product. Note: id (used as catalogProductId), the exact colour names, the sizes and the print-area keys (e.g. front, back) with their dimensions in mm.
  3. 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.
  4. Import products: Exactly one call of POST /products per 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
  ]
}
  1. 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.
  2. 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 shopSku is already taken – that variant already exists, do not recreate the product.
  3. Reconcile: GET /products and verify every shop product has exactly one NEXT product with all variants and shop SKUs.
  4. Test order: POST /orders with an old shop SKU. Expected result: status checked (not clarification).

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.