Shop API

Categories for the admin picker / filter chips.

Get a single shop order by ID (admin).

List shop orders with filters, sorting, and pagination (admin).

Get inventory adjustment history for an inventory record.

Get inventory for a specific product (and optionally a variant).

Get all inventory records for a shop.

Get inventory summary counts for a shop.

List product categories for admin with filtering, sorting, and pagination.

List products for admin with filtering, sorting, and pagination.

List shop categories with admin filters, sorting, and pagination. # Authorization Requires TenantAdmin or PlatformAdmin role.

List shops with admin filters, sorting, and pagination. # Authorization Requires TenantAdmin or PlatformAdmin role.

Get the current user's cart. Creates a new cart if one doesn't exist. Includes delivery fee preview and per-method delivery options when a delivery address with coordinates is set.

Get cart item count (for nav badge).

Get featured products (discounted or high display priority). Optionally filtered by *product* category (menu section).

Get the current user's merchant profile.

List inventory rows for one of the current merchant's shops. Optional filters narrow the result to only low-stock or only out-of-stock items (out-of-stock takes precedence when both are set).

Low-stock and out-of-stock counts for one of the current merchant's shops — powers the vendor home "needs restock" summary.

Get a single shop order by ID for the authenticated customer. Returns None if the order doesn't exist or doesn't belong to the customer.

Get all shop orders for the current customer.

List **all** products for one of the current merchant's shops — the management view — regardless of status or availability. Unlike the customer-facing products query (which only returns Active + available products), this also returns Draft, OutOfStock, and is_available = false products, so a merchant can see and re-enable a product they have marked sold out, or publish a freshly-created draft. Scoped to shop_id after verifying ownership. An optional product_category_id narrows the list to a single menu section; the category is verified to belong to the shop first, so a merchant can't read another shop's catalog by passing a foreign category id.

Get shops owned by the current merchant.

Weekly sales chart (revenue + order count per week) for one of the current merchant's shops. Scoped to shop_id after verifying ownership; currency is the merchant's own currency. Optional date range narrows the window.

Get a product by ID.

Get all availability schedule entries for a product.

Discover products within a shop with optional search, category, and tag filters. Replaces browseProducts, searchProducts, and productsByTags with a single query. **Filter priority:** 1. If query is set → full-text search on name/description/tags 2. Else if tags is set → filter products matching any tag 3. Else if product_category_id is set → filter by product category 4. Else → all active products in the shop

Get product variants for a product.

All categories for the system tenant — drives the filter-chip row on /blog.

Semantic product search. Embeds the free-text query, then ranks products by cosine similarity against their stored description_embedding. Requires the tenant to have semantic_search_enabled turned on under Settings → AI Features and at least one configured embedding-capable AI provider with remaining monthly budget.

Get a shop by ID. location is optional and, when supplied, makes deliveryFee address-aware (zone fee, or a live express quote for an express-only shop). Omitting it keeps the previous behaviour (null fee).

Get a shop by slug. Accepts the same optional location as [shop] to make deliveryFee address-aware on the detail path.

Get all shop categories. Returns enabled categories sorted by display order.

Get all shop categories with their subcategories.

Get a shop category by ID.

Get a shop category by slug.

List delivery zones for a specific shop (admin).

Get a single order by ID for one of the current merchant's shops. Returns None when no order matches the id. Errors if the order exists but belongs to a shop the current merchant does not own, mirroring the ownership check in [MerchantQuery::shop_orders] — a merchant must never be able to read another merchant's order by guessing its id.

Get orders for a specific shop owned by the current merchant. Supports filters, sorting, and pagination.

Get aggregate statistics for shop orders. Filters by currency (required) and an optional date range. Statistics are computed across all shops for the current tenant.

List a shop's enabled product categories (its menu sections), ordered for display. Each returned category resolves its own nested products, so the customer app can fetch a shop's entire catalog grouped by category in one request on shop open. These are *product* categories (per-shop menu sections), distinct from the shop's *business* categories exposed as Shop.categories / shopCategories.

Discover shops with optional search, location, category, and open-status filters. Replaces browseShops, nearbyShops, and searchShops with a single unified query. **Filter priority:** 1. If query is set → full-text search on name/description 2. Else if location is set → proximity search sorted by distance 3. Else if shop_category_id is set → filter by shop (business) category 4. Else if shop_subcategory_id is set → filter by shop subcategory 5. Else → all enabled shops currently_open_only is always applied as a post-filter if set.

Get several shops by ID, in the order requested. Serves the pinned storefront modes: shopStorefront hands the client a short list of shop ids, and this turns them into cards for the store switcher in one round-trip. Deliberately not a filter on [shops](Self::shops) — that query's job is discovery (pagination, sorting, proximity, category), none of which applies to a set the server already chose. Ids belonging to another tenant, or that no longer exist, are dropped rather than erroring: a pinned shop can be disabled between the config read and this call, and a half-rendered switcher beats a failed screen. location behaves as on [shop](Self::shop) — supplying it makes deliveryFee address-aware. Express quotes stay off: this renders a list, and each quote is an external routing call.

Service health check query.

The storefront the calling tenant's shop app should render. Read by shop_customer at startup, before login — a bpk_ public client key is enough, since the answer is the same for every customer of the tenant and the app must know which listing to draw on its first frame. Returns platform defaults when the tenant has never configured it, so this never errors for a valid tenant.

Get subcategories for a category.

Accept an incoming shop order.

Add an item to the cart.

Adjust a product's on-hand stock by a signed delta, recording an audited adjustment. Positive adds stock, negative removes it.

Add stock to an inventory record.

Create an inventory record for a product (or product variant).

Create a shop order on behalf of a customer (call-center dispatcher path). # Authorization Requires TenantAdmin or PlatformAdmin role. # Behaviour - Validates the shop is enabled and belongs to the calling tenant. - Loads each product to lock in its current price (no cart/quote round-trip). - Computes pricing: subtotal = sum of unit_price × quantity, delivery_fee = shop.delivery_fee_minor when delivering (else 0), total = subtotal + delivery_fee. Tax and service fees are zero in the dispatcher path; they remain a server-driven concern for customer-placed orders that go through the cart flow. - Generates a fresh parent order_id UUID — shop orders persist independently of the order-domain Order row, matching the existing schema (no FK enforcement). - Persists with status: New, prep_status: Pending so it appears on the merchant's incoming-orders queue exactly like a normal order.

Soft-delete a product by setting its status to discontinued.

Remove stock from an inventory record.

Set the absolute stock quantity for an inventory record.

Update discount settings for a product. Set discount_percentage to null to remove the discount entirely.

Update a shop's status as an admin. # Authorization Requires TenantAdmin or PlatformAdmin role. # Validation Shop status is operational-only (approval lives on the merchant — a shop goes live when its merchant is approved via approveMerchant). The new status must be a permitted transition from the current status: - Disabled → Enabled | Archived - Enabled → Disabled | Blocked - Blocked → Enabled | Archived Archived is terminal. Any other transition returns an error.

Apply a promo code to the cart.

Approve a merchant (admin only). Sets merchant status to Approved and marks as verified.

Checkout the current cart: validates shops, locks prices, and returns a quote ID. The returned quoteId should be passed to createOrder(quoteId, kind: SHOP, ...). The quote expires after 5 minutes — call again if expired.

Clear all items from the cart.

Create a delivery zone on a shop owned by the calling merchant.

Create a new product.

Create a new product availability schedule entry.

Create a new product category. Admins may target any shop; merchants only their own shops.

Create a new product option within a group.

Create a new shop.

Create a new shop category. # Authorization Requires TenantAdmin or PlatformAdmin role.

Create a new delivery zone for a shop.

Delete a delivery zone — caller must own the shop it belongs to.

Delete a product availability schedule entry.

Delete a product category.

Delete a product option.

Delete a shop category by ID. # Authorization Requires TenantAdmin or PlatformAdmin role.

Delete a delivery zone.

Compute embeddings for every still-NULL product under this tenant (or one shop, when shop_id is provided). Tenant-admin only. Bounded internally; the admin re-runs until moreRemaining is false. Plan gate (Pro+) is enforced inside the EmbeddingPort dispatcher.

Compute and store the embedding for one product. Tenant-admin only. Requires the tenant to have semantic_search_enabled turned on under Settings → AI Features and at least one configured embedding-capable AI provider with remaining monthly budget. Plan gate (Pro+) is enforced inside the EmbeddingPort dispatcher.

Generate a draft product suggestion from a single product photo. Tenant-admin only. Requires the tenant to have product_description_gen_enabled turned on under Settings → AI Features and at least one configured AI provider with remaining monthly budget.

Mark an order as delivered.

Mark an order as picked up.

Mark an order as ready for pickup/delivery.

Register as a merchant.

Reject an incoming shop order.

Remove an item from the cart.

Remove a promo code from the cart.

Reorder options within a group.

Set the delivery address for the cart. Only requires the saved location ID — coordinates are resolved server-side from the identity service.

Set the delivery mode for the cart.

Atomically replace a product's full availability schedule. Passing an empty windows list clears the schedule (the product becomes available whenever the shop is open).

Set a product's on-hand stock for one of the current merchant's shops. Creates the inventory row if absent and turns on inventory tracking for the product so fulfillment reserves against it.

Replace the set of categories associated with a merchant's shop. Validates that all category IDs belong to the same tenant and are enabled before making any changes. Diffs current vs requested and issues only the needed add/remove calls.

Atomically replace the full set of delivery zones on a shop. Used by the onboarding form which collects all zones together — one transactional call avoids the partial-failure / duplicate- zone states the per-zone create_delivery_zone path produced on retry.

Set operating hours for a shop (bulk replace all days).

Set the tenant's storefront mode, pinned shops and cart scope. Requires TenantOwner, TenantAdmin or PlatformAdmin. Returns the freshly-resolved storefront rather than the raw stored config, so the settings UI can show the effect of the change — most importantly what AUTO worked out to — without a second round-trip.

Service health check mutation.

Start preparing an order.

Submit the caller's merchant profile for admin review. Transitions the merchant Pending → PendingReview (or re-submits from Rejected). This is the single approval signal: the merchant enters the admin approval queue here, and approve_merchant — which also enables the merchant's onboarding shop — is the counterpart. Shop status is operational-only and carries no approval state.

Toggle product availability.

Toggle a product option's enabled state.

Toggle shop open/closed state.

Update item quantity in cart.

Update a delivery zone — caller must own the shop the zone lives on.

Update merchant profile.

Update an existing product availability schedule entry.

Update an existing product category.

Update an existing product. Set, change, or clear a product's discount on one of the caller's shops. Null fields clear the corresponding value (no discount / unlimited quantity / no expiry) — mirrors adminUpdateProductDiscount but scoped to the merchant's own products.

Update an existing product option.

Update product status (draft, active, discontinued).

Update an existing shop.

Update an existing shop category. # Authorization Requires TenantAdmin or PlatformAdmin role.

Update an existing delivery zone.

Subscribe to shop customer events (Shop service) Receive real-time events relevant to shop customers: - Order confirmations - Shipment tracking updates - Delivery notifications - Notifications **Requirements:** - Must be authenticated - Must have Customer role - Must be using Shop app

Subscribe to vendor events (Shop service) Receive real-time events relevant to shop vendors: - New order notifications - Inventory alerts - Payment received notifications - Notifications **Requirements:** - Must be authenticated - Must have Vendor role - Must be using Shop app