API overview

Base URL, authentication, pagination and conventions of the API reference generated from OpenAPI.

The pages in this tab are generated from OpenAPI specifications: a separate one for the Storefront API v1 (public, no key) and one for the Shop API (key or session). Each endpoint has an interactive “Try it” form. The reference covers the public API — internal panel routes (login, AI assistant, billing) aren’t published here.

​

Base URL

https://itemshop.dev/api/v2

Locally: http://localhost:3000/api/v2. Every path has the /api/v2 prefix.

​

Which API for what

API	Authentication	Used for
Storefront API v1 (/storefront/v1/..., from 3.0)	none — public, CORS, cached	your shop website’s data in the browser: shop, products, payment methods, checkout, order status, widgets. See Storefront API.
Shop API (this reference)	X-API-Key (apiKeyAuth)	server-side integrations: products, orders, discounts, vouchers, stats, team, and from 3.0 site files and deployments
panel routes	session Authorization: Bearer (bearerAuth)	account, creating a shop, key management, owner-only actions

​

Authentication

An endpoint may require bearerAuth, apiKeyAuth, accept both, or be public — every reference page shows which. For integrations use a shop key:

X-API-Key: isk_<64 hex chars>

If an endpoint accepts a key and the request carries both mechanisms, the key is checked. A plain Bearer route ignores the key and uses the session. Creating keys and scopes: API with a key.

Public (no authentication) endpoints include: creating an order, public shop catalogs, voucher redemption, discount-code validation, order status and payment-provider webhooks. Public doesn’t mean unlimited — validation and rate limits apply, and checkout also requires consents, the document version, an Idempotency-Key and Turnstile.

​

Response conventions

Success: { success: true, data, message? }. Error: { success: false, statusCode, error, code?, details?, timestamp, path }. Always check the success field. Codes and retries: Errors and limits.

​

Identifiers

Resource ids (shopId, serverId, orderId, …) are MongoDB ObjectIds — 24 hex chars (^[0-9a-fA-F]{24}$). An invalid format returns 400.

​

Pagination and limits

Lists accept page (from 1) and limit. A paginated response contains data, total, page, pages, hasNext and hasPrev. limit is clamped to a safe maximum (usually 100; stats lists have their own lower caps). Example:

curl "https://itemshop.dev/api/v2/orders/<shopId>?status=paid&page=2&limit=50" \
  -H "X-API-Key: $ITEMSHOP_API_KEY"

The global limit is 200 requests per minute per IP, and sensitive routes have stricter windows — see Errors and limits.

​

Next

API with a key

Create a key and send your first request.

Storefront API

Public shop data for your website.