API Reference — Next Commerce

📖

Overview

🏭 Manufacturer API

Products, dealers, webhooks, GPSR compliance

🏪 Dealer API

Inventory, assignments, Stripe payouts

🔒 Session-Cookie

NextAuth.js. Public widget endpoints need no auth.

📦 application/json

Default. Exceptions marked multipart/form-data.

⚙️

Conventions

Field	Note	Example
Preise	Integer · Cent	`2500` = 25.00 EUR
Countries	ISO 3166-1 alpha-2	`DE`, `AT`, `CH`
Timestamps	ISO 8601	`2026-04-17T10:30:00Z`
SKU	Unique per brand	`brandId + sku`

Pagination Envelope

{
  "success": true,
  "data": [...],
  "pagination": {
    "page": 1, "limit": 30, "totalCount": 142,
    "hasNextPage": true, "hasPreviousPage": false
  }
}

🔑

Authentication

Session-Cookie via NextAuth.js

ℹ️

Session cookie: All dashboard APIs require a valid session cookie. Public widget/checkout endpoints are auth-free.

POST/api/auth/registerRegister

Creates a new account. type: brand for manufacturers, dealer for dealers.

Field	Type	Required	Note
type	"brand"\|"dealer"	Yes
email	string	Yes	Unique
password	string	Yes	Min 8 chars
firstName/lastName	string	Yes
companyName	string	No
baseCurrency	string	No	Dealer only, immutable after signup
product	string	No	`DEALER_CHECKOUT` \| `LISTINGSHIELD`
invitationId	string	No

Response 200

{
  "success": true,
  "userId": "cuid_xxx",
  "role": "BRAND",
  "redirectUrl": "/brand"
}

⚠️

Rate limit: 5 / min / IP · 5 / 24h / email

POST/api/auth/callback/credentialsSign In

POST/api/auth/forgot-passwordForgot password

GET/api/auth/verify-email?token=xxxVerify email

📦

Manufacturer — Products

role: BRAND

GET/api/brand/products?page=1&limit=30List

POST/api/brand/productsCreate

Field	Type	Required	Note
sku	string	Yes	Unique per brand
name	string	Yes
description	string	Yes
weight	number	Yes	kg
recommendedPrice	integer	No	Cent
images	string[]	No	URLs
nameTranslations	object	No	{"en":"..."}
category	string	No
countryOfOrigin	string	No	ISO
internalProductId	string	No

⚠️

400 "SKU already exists for this brand"

GET/api/brand/products/:idGET / PUT / DELETE

POST/api/brand/products/bulk-importCSV Import

Content-Type: multipart/form-data

Field	Type	Required	Note
csv	File	Yes
zip	File	No
mode	string	Yes	`create_only` \| `update_only` \| `create_and_update`
skipTranslation	boolean	Yes	Skip DeepL
action	string	Yes	`validate` \| `import`

Response 200

{
  "totalProcessed": 50, "successCount": 48, "failureCount": 2,
  "results": [
    { "sku": "ABC-123", "success": true, "action": "created" },
    { "sku": "DEF-456", "success": false, "error": "Invalid weight" }
  ]
}

SSE progress: GET /api/brand/products/bulk-import/progress/:importId

POST/api/brand/products/bulk-assignBulk assign

POST/api/brand/products/activateActivate module

🤝

Manufacturer — Dealers

role: BRAND

GET/api/brand/dealers?productId=xxxList

PATCH/api/brand/dealers/countriesUpdate countries

POST/api/brand/dealers/:dealerId/assign-productsAssign products

POST/api/brand/invitationsInvite dealer

Field	Required
recipientEmail	Yes
recipientFirstName	No
country	No
assignedProductIds	No

🔔

Manufacturer — Webhooks

role: BRAND

💡

Webhooks send POST on order events. Retry backoff: 1 min → 5 min → 30 min → 2h → 24h.

POST/api/brand/webhooksCreate

Field	Note
url	HTTPS endpoint
events	`["order.created", "order.confirmed", "order.fulfilled"]`
isActive	boolean

GET|POST /api/brand/webhooks · PATCH|DELETE /api/brand/webhooks/:id
POST /api/brand/webhooks/:id/test · GET /api/brand/webhooks/:id/logs

🛡️

Manufacturer — Compliance / GPSR

role: BRAND · ListingShield

ℹ️

Compliance cascades: brand → category → product. Product-level values override category values.

GET/api/brand/compliance/companyCompany GPSR

POST/api/brand/compliance/categoriesCategory compliance

Field	Note
categoryName
safetyWarnings
ageRestriction
warrantyInfo
disposalInstructions

GET/api/brand/products/:id/complianceProduct compliance

POST/api/brand/compliance/invite-dealerInvite to ListingShield

Field	Required	Note
websiteUrl	Yes
contactEmail	Yes
createNew	No	Force create if duplicate domain

📦

Dealer — Inventory

role: DEALER

POST/api/dealer/inventoryAdd product

Field	Type	Required	Note
sku	string	Yes	Product SKU
brandId	string	Yes
price	integer	Yes	Cent
stockLevel	integer	Yes
discount	number	No	%
deliveryDays	integer	No	Default: 3

Response 200

{
  "success": true,
  "inventory": { "price": 19900, "stockLevel": 50, "deliveryDays": 3 }
}

⚠️

403 not authorized · 400 product already in inventory

PUT/api/dealer/inventory/:idUpdate

DELETE/api/inventory/:idDelete

📋

Dealer — Assignments

role: DEALER

GET/api/dealer/assignments?status=PENDINGList

POST/api/dealer/assignments/:id/acceptAccept

Field	Required	Note
price	Yes	Cent
stockLevel	No
deliveryDays	No	Default: 3

DELETE/api/dealer/assignments/:idReject

🛒

Dealer — Orders

role: DEALER

POST/api/dealer/orders/refundProcess refund

💡

Stripe automatically reverses dealer transfer and platform fee proportionally.

Field	Required	Note
orderId	Yes
refundType	Yes	`"full"` \| `"partial"`
reason	Yes
totalAmount	Yes	Cent
refundedItems	No	[{productId, sku, quantity, amount}]
shippingRefund	No	Cent

💰

Händler — Stripe

role: DEALER

💡

Dealers receive their margin via Stripe Split-Payment automatically at checkout.

POST/api/dealer/stripe/onboarding-linkStart onboarding

📡

Webhook Events

Event	When
order.created	Order created, awaiting payment
order.confirmed	Payment succeeded
order.fulfilled	Order shipped/fulfilled

Webhook Payload

{
  "event": "order.created",
  "timestamp": "2026-04-17T10:30:00Z",
  "data": {
    "orderId": "order_id", "orderCode": "ORD-12345",
    "grandTotal": 10700, // 107,00 EUR
    "currency": "EUR",
    "customer": { "email": "customer@example.com" },
    "items": [{ "sku": "ABC-123", "quantity": 1, "dealerId": "dealer_id" }]
  }
}

⚠️

Errors & HTTP Codes

Error Format

{
  "error": "Human-readable message",
  "code": "MACHINE_READABLE_CODE",
  "required": ["field1"]
}

Status	Meaning
`200`	OK
`400`	Validation error
`401`	Not authenticated
`403`	Not authorized / COUNTRY_NOT_ASSIGNED
`404`	Not found
`409`	Conflict
`429`	Rate limited
`500`	Server error

🚦

Rate Limits

Tier	Limit	Window	Applies To
AUTH	5	1 min / IP	Register, login, password reset
REGISTRATION_EMAIL	5	24h / email	Registration only
AUTHENTICATED	500	1 min / IP	All dashboard APIs
PUBLIC	100	1 min / IP	Widget, checkout

429 Response

{ "error": "Too many requests", "retryAfter": 45 }

Next Commerce API

Overview

Conventions

Authentication

Manufacturer — Products

Manufacturer — Dealers

Manufacturer — Webhooks

Manufacturer — Compliance / GPSR

Dealer — Inventory

Dealer — Assignments

Dealer — Orders

Händler — Stripe

Webhook Events

Errors & HTTP Codes

Rate Limits