Shop API

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 category.

Get the current user's merchant profile.

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.

Get shops owned by the current merchant.

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 category_id is set → filter by product category 4. Else → all active products in the shop

Get product variants for a product.

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.

Get a shop by slug.

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 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.

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 category_id is set → filter by category 4. Else if subcategory_id is set → filter by subcategory 5. Else → all enabled shops currently_open_only is always applied as a post-filter if set.

Service health check query.

Get subcategories for a category.

Accept an incoming shop order.

Add an item to the cart.

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 The new status must be a permitted transition from the current status. Allowed transitions: - PendingApproval → Enabled (alias: approve via approveMerchant) - PendingApproval → Blocked - Enabled → Disabled | Blocked - Disabled → Enabled | Archived - 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.

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.

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).

Service health check mutation.

Start preparing an order.

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.

Update an existing product availability schedule entry.

Update an existing product category.

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