{"openapi":"3.1.0","info":{"title":"Shirtking.NEXT API","version":"1.0.0","description":"Versioned REST API. Authenticate with `Authorization: Bearer skn_…`. Limit 120 requests/minute per key. All amounts are net cents. Errors: `{ error: { code, message } }`."},"servers":[{"url":"/api/public/v1"}],"security":[{"bearer":[]}],"paths":{"/catalog":{"get":{"summary":"List base articles (colours, sizes, print methods, print areas) for imports","description":"Scope: read","parameters":[{"name":"page","in":"query","schema":{"type":"integer","minimum":1}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"q","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Page of results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page"}}}},"401":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/products":{"get":{"summary":"List products with approved variants (SKUs), linked shop SKUs and mockup image links","description":"Scope: read. Each product and variant has `images` (colour, side front/back, url). URLs are signed download links valid for 6 hours (`imagesExpireInSeconds`): download and host the files yourself; call again for fresh links. `include=none` omits images.","parameters":[{"name":"page","in":"query","schema":{"type":"integer","minimum":1}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"include","in":"query","schema":{"type":"string","enum":["images","none"]}}],"responses":{"200":{"description":"Page of results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page"}}}},"401":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}},"post":{"summary":"Import a product","description":"Scope: products:write. Requires `Idempotency-Key`. Downloads each artwork (public HTTPS, PNG/SVG/PDF, max 50 MB), creates and approves the product and links optional `shopSku` values so existing shop orders with those SKUs are recognised automatically.","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","maxLength":200}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductInput"}}}},"responses":{"201":{"description":"Created"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/products/{id}":{"patch":{"summary":"Update product name, SKU prefix or active flag","description":"Scope: products:write. A new `skuPrefix` must be unique in your account and applies to new versions; already approved SKUs stay unchanged.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"skuPrefix":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_-]{1,15}$"},"active":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Updated"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}},"delete":{"summary":"Delete a product","description":"Scope: products:write. Fails with 409 product_in_use if it was ever ordered (deactivate instead).","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Deleted"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"}}}},"/products/{id}/versions/{version}":{"delete":{"summary":"Discard a draft version","description":"Scope: products:write. Only drafts; if it is the only version, the product is deleted.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"version","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Discarded"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"}}}},"/orders/{id}/cancel":{"post":{"summary":"Cancel an order","description":"Scope: orders:write. Allowed until the order is handed over to production (statuses received, checked, clarification, released); then 409 cancellation_not_allowed. Payments are refunded automatically. Repeating on a cancelled order returns 200 with meta.alreadyCancelled.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Order id or order number"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","maxLength":500}}}}}},"responses":{"200":{"description":"Cancelled order"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"}}}},"/package-insert":{"get":{"summary":"Package insert status","description":"Scope: read. Package inserts are not order items: while enabled and in stock, one is added automatically to every parcel (fee per parcel). Configure and restock in the portal.","responses":{"200":{"description":"Status"}}}},"/inventory":{"get":{"summary":"List stock items with Heldenbrain-mirrored levels","description":"Scope: inventory:read or read","parameters":[{"name":"page","in":"query","schema":{"type":"integer","minimum":1}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100}}],"responses":{"200":{"description":"Page of results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page"}}}},"401":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/orders":{"get":{"summary":"List orders","description":"Scope: read","parameters":[{"name":"page","in":"query","schema":{"type":"integer","minimum":1}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"status","in":"query","schema":{"type":"string"}},{"name":"updated_since","in":"query","schema":{"type":"string","format":"date-time"}}],"responses":{"200":{"description":"Page of results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page"}}}},"401":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}},"post":{"summary":"Create an order","description":"Scope: orders:write. Requires `Idempotency-Key` header; repeating a key with the same body replays the first response.","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","maxLength":200}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderInput"}}}},"responses":{"201":{"description":"Created"},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"}}}},"/orders/{id}":{"get":{"summary":"Get order by id or order number","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Order"},"404":{"$ref":"#/components/responses/Error"}}}},"/shipments":{"get":{"summary":"List shipments and tracking numbers","description":"Scope: read","parameters":[{"name":"page","in":"query","schema":{"type":"integer","minimum":1}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100}}],"responses":{"200":{"description":"Page of results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page"}}}},"401":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/invoices":{"get":{"summary":"List invoices and credit notes","description":"Scope: read","parameters":[{"name":"page","in":"query","schema":{"type":"integer","minimum":1}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100}}],"responses":{"200":{"description":"Page of results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page"}}}},"401":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}}},"webhooks":{"event":{"post":{"summary":"Event delivery","description":"Signed with header `x-shirtking-signature: t=<unix>,v1=<hex>` where v1 = HMAC-SHA256(secret, `${t}.${body}`). Retried with exponential backoff (2,4,8… minutes), 8 attempts max. Events: order.created, order.accepted, order.clarification, order.in_production, order.shipped, order.cancelled, inventory.low, inventory.updated, invoice.created, complaint.updated.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"createdAt":{"type":"string"},"data":{"type":"object"}}}}}},"responses":{"2XX":{"description":"Acknowledged"}}}}},"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer"}},"responses":{"Error":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}},"schemas":{"Page":{"type":"object","properties":{"data":{"type":"array","items":{}},"meta":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"hasMore":{"type":"boolean"}}}}},"ProductInput":{"type":"object","required":["name","catalogProductId","prints","variants"],"properties":{"name":{"type":"string"},"skuPrefix":{"type":"string","description":"Optional, unique per account; default derived from name"},"catalogProductId":{"type":"string","format":"uuid"},"printMethod":{"type":"string"},"shopId":{"type":"string","format":"uuid"},"prints":{"type":"array","items":{"type":"object","required":["area","artworkUrl","widthMm","heightMm"],"properties":{"area":{"type":"string","description":"Print area key from /catalog"},"artworkUrl":{"type":"string","format":"uri"},"widthMm":{"type":"number"},"heightMm":{"type":"number"},"offsetXMm":{"type":"number","description":"mm from zone top-left"},"offsetYMm":{"type":"number"},"rotation":{"type":"number"}}}},"variants":{"type":"array","items":{"type":"object","required":["color","size"],"properties":{"color":{"type":"string"},"size":{"type":"string"},"shopSku":{"type":"string","description":"Existing SKU in your shop (e.g. from podOS)"}}}}}},"OrderInput":{"type":"object","required":["externalRef","shippingAddress","items"],"properties":{"externalRef":{"type":"string"},"notes":{"type":"string"},"shippingAddress":{"type":"object","required":["name","street","postalCode","city","country"],"properties":{"name":{"type":"string"},"company":{"type":"string"},"street":{"type":"string"},"addressLine2":{"type":"string"},"postalCode":{"type":"string"},"city":{"type":"string"},"country":{"type":"string","pattern":"^[A-Z]{2}$"},"email":{"type":"string"}}},"items":{"type":"array","items":{"type":"object","required":["sku","quantity"],"properties":{"sku":{"type":"string"},"quantity":{"type":"integer","minimum":1}}}}}}}}}