Commerce Endpoints

Customer-facing and merchant commerce endpoints introduced in KUB-207 (eCommerce + Merchant MVP).

All endpoints use the /api/v1 prefix. Auth is via Bearer token unless noted. Full request/response schemas are in the API Reference and the live OpenAPI spec at GET /api/v1/openapi.

Cart

Method	Path	Auth	Description
GET	/api/v1/cart	Bearer	Get authenticated user's cart (or null)
POST	/api/v1/cart/items	Bearer	Add product with required positive-integer product_id and place_id (400 validation; 404 unavailable membership; 409 cross-merchant conflict)
PATCH	/api/v1/cart/items/:id	Bearer	Update cart line quantity (0 removes)
DELETE	/api/v1/cart/items/:id	Bearer	Remove single cart line
DELETE	/api/v1/cart	Bearer	Clear entire cart

Checkout

Method	Path	Auth	Description
POST	/api/v1/checkout	Bearer	Atomic checkout: order + PaymentIntent + cart clear. Requires the Idempotency-Key header (400 if missing/empty; max 255 chars).

Storefront (Public)

Method	Path	Auth	Description
GET	/api/v1/places/:id/menu	None	Public menu: categories + visible items for a place

Payment Methods

Method	Path	Auth	Description
POST	/api/v1/me/payment-methods/setup-intent	Bearer	Create Stripe SetupIntent (rate limiter defined but not wired)
POST	/api/v1/me/payment-methods	Bearer	Persist payment method after SetupIntent flow
GET	/api/v1/me/payment-methods	Bearer	List user's linked payment methods (no PCI fields)
PATCH	/api/v1/me/payment-methods/:id/default	Bearer	Set a payment method as default
DELETE	/api/v1/me/payment-methods/:id	Bearer	Detach and soft-delete payment method

Orders

Method	Path	Auth	Description
GET	/api/v1/me/orders	Bearer	Customer order history (paginated, filterable)
GET	/api/v1/me/orders/:id	Bearer	Single order with line items
GET	/api/v1/me/orders/:id/status	Bearer	Lightweight status polling (30s during pending_payment)

Place Claims

Method	Path	Auth	Description
POST	/api/v1/place-claims	Bearer	Submit ownership claim on a place (5 req/hour rate limit)
GET	/api/v1/place-claims?mine=true	Bearer	List calling user's claims with status

Merchant Onboarding

Method	Path	Auth	Description
POST	/api/v1/me/places/:placeId/payment-details	Bearer + merchant	Save payout details (encrypted at rest). Fields: bank_name, account_holder_name, account_number, mobanking_phone_number, currency (default: XCD)
PATCH	/api/v1/me/places/:placeId/payment-details	Bearer + merchant	Update payout details
GET	/api/v1/me/places/:placeId/payment-details	Bearer + merchant	Get payout details (last4 only for merchant)

Merchant Inventory

Method	Path	Auth	Description
GET	/api/v1/me/places	Bearer + merchant	List places owned by the authenticated merchant
GET	/api/v1/me/places/:placeId/orders	Bearer + merchant	List orders for a place
POST	/api/v1/me/places/:placeId/categories	Bearer + merchant	Create a storefront category
PATCH	/api/v1/me/places/:placeId/categories/:id	Bearer + merchant	Update a category
DELETE	/api/v1/me/places/:placeId/categories/:id	Bearer + merchant	Delete a category
POST	/api/v1/me/places/:placeId/items	Bearer + merchant	Create a storefront item
PATCH	/api/v1/me/places/:placeId/items/:itemId	Bearer + merchant	Update an item
DELETE	/api/v1/me/places/:placeId/items/:itemId	Bearer + merchant	Delete an item
POST	/api/v1/me/places/:placeId/items/:itemId/prices	Bearer + merchant	Append a price (prices are append-only)

Disbursements

Method	Path	Auth	Description
GET	/api/v1/me/disbursements	Bearer + merchant	Merchant's disbursement history (read-only)
GET	/api/v1/me/disbursements/:id	Bearer + merchant	Single disbursement detail

Push Notifications

Method	Path	Auth	Description
POST	/api/v1/me/push-tokens	Bearer	Register or refresh device push token
DELETE	/api/v1/me/push-tokens/:device_id	Bearer	Remove device push token on logout

Shop QR

Method	Path	Auth	Description
GET	/api/v1/me/places/:place_id/shop-qr	Bearer + merchant + owns place	Deep-link URL and QR SVG for the place

Internal Endpoints

These private Hono↔Laravel routes are behind the InternalOnly middleware (X-Internal-Token header) and are not available to external clients. They handle payment-details encryption, Stripe SetupIntent/customer operations, and order-state transitions. Client documentation is omitted by design — treat this as a trust boundary.

See Also

• API Overview — full request/response schemas and live OpenAPI endpoint
• Stripe Webhook Integration — webhook setup and event processing