Storefront API — Getting Started

The Quark Commerce Storefront API is a RESTful API designed for building customer-facing e-commerce experiences — whether web, mobile, or any other platform. All endpoints are prefixed with /api/storefront/.

Base URL

Environment	URL
Local development	http://localhost:8080
Production	https://quarkapi.yourdomain.com

Quick Start

1. Get store configuration

curl -H "X-Store-Code: us-store" \
     http://localhost:8080/api/storefront/store-config

This returns the store's supported languages, currencies, and default settings.

2. Browse categories

curl -H "X-Store-Code: us-store" \
     -H "X-Language-Code: en" \
     http://localhost:8080/api/storefront/categories

3. Get products by category

curl -H "X-Store-Code: us-store" \
     -H "X-Language-Code: en" \
     -H "X-Currency-Code: USD" \
     http://localhost:8080/api/storefront/products/category/{categoryId}?page=1&pageSize=20

4. Add to basket

curl -X POST \
     -H "Content-Type: application/json" \
     http://localhost:8080/api/storefront/basket/{basketId}/items \
     -d '{"productVariantId": "...", "quantity": 1}'

5. Checkout

curl -X POST \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     http://localhost:8080/api/storefront/checkout/session \
     -d '{"basketId": "...", "shippingAddress": {...}}'

Required Headers

Every storefront request should include context headers:

Header	Required	Description
X-Store-Code	Yes	Store identifier (e.g., us-store, tr-store)
X-Language-Code	Yes	Content language (e.g., en, tr)
X-Currency-Code	Recommended	Pricing currency (e.g., USD, TRY)
Authorization	For auth endpoints	Bearer <jwt-token>

See Store Context for details on how these headers work.

Endpoint Overview

Controller	Base Route	Description
StoreConfig	/api/storefront/store-config	Store settings, languages, currencies
Categories	/api/storefront/categories	Category tree and details
Products	/api/storefront/products	Product listing, detail, search
Brands	/api/storefront/brands	Brand listing
Basket	/api/storefront/basket	Shopping basket CRUD
Checkout	/api/storefront/checkout	Checkout session management
Orders	/api/storefront/orders	Order history and details
Payments	/api/storefront/payments	Payment processing callbacks
Shipping	/api/storefront/shipping	Shipping method calculation
Availability	/api/storefront/availability	Stock availability checks
Auth	/api/auth	Login, register, password reset
Profile	/api/storefront/profile	User profile management
Addresses	/api/storefront/addresses	Address book
Slugs	/api/storefront/slugs	SEO slug resolution
Navigation	/api/storefront/navigation	Navigation menus
Pages	/api/storefront/pages	CMS pages and content blocks
Documents	/api/storefront/documents	Legal documents
GDPR	/api/storefront/gdpr	Data export and deletion
Countries	/api/storefront/countries	Country/region listing
Verification	/api/storefront/verification	Phone/email verification

Swagger

Interactive API documentation is available at:

http://localhost:8080/swagger

tip

While Swagger shows all endpoints and their request/response shapes, this documentation explains the relationships between entities, required flows (e.g., the checkout sequence), and design decisions that are not visible in Swagger alone.