adminBlogCategories
#Categories for the admin picker / filter chips.
Arguments
- tenantIdID
Catalog, products, vendors, categories, merchant operations, inventory, and the shop's own couriers.
Categories for the admin picker / filter chips.
Arguments
The workspace's courier assignments made within the filter's range, newest first: every courier and shop, or the slice the filter names.
Arguments
Default
{
"limit": 10,
"page": 1,
"after": null
}Every courier on shift right now, with where they last were, read from the live presence store: the console's courier map. A courier whose app has not reported for three minutes is no longer on it.
Arguments
The workspace's shift log: one page of the shifts started within the filter's range, newest first.
Arguments
Default
{
"limit": 10,
"page": 1,
"after": null
}Deprecation reason: Use adminGetShopOrdersWithValues; BET-205
Arguments
Default
{
"limit": 10,
"page": 1,
"after": null
}Default
[]List shop orders with filters, sorting, and pagination (admin).
Arguments
Default
{
"limit": 10,
"page": 1,
"after": null
}Default
[]List product categories for admin with filtering, sorting, and pagination.
Arguments
Default
{
"limit": 10,
"page": 1,
"after": null
}Default
{
"shopId": null,
"isEnabled": null,
"search": null
}Default
[]List products for admin with filtering, sorting, and pagination.
Arguments
Default
{
"limit": 10,
"page": 1,
"after": null
}Default
{
"shopId": null,
"categoryIds": [],
"status": null,
"search": null
}Default
[]List shop categories with admin filters, sorting, and pagination. # Authorization Requires TenantAdmin or PlatformAdmin role.
Arguments
Default
{
"limit": 10,
"page": 1,
"after": null
}Default
[]List shops with admin filters, sorting, and pagination. # Authorization Requires TenantAdmin or PlatformAdmin role.
Arguments
Default
{
"limit": 10,
"page": 1,
"after": null
}Default
[]Every badge a shop holds, whatever its window: showing now, scheduled
ahead, or already over. Shop.badges carries only those showing now.
Arguments
What the workspace keeps of its shops' sales. Staff only.
The workspace's couriers, newest first: every team and the pool, or the slice the filter names.
Arguments
Default
{
"limit": 10,
"page": 1,
"after": null
}The terms one shop sells on: its commission and the share of a courier's fee it pays. Staff only.
Arguments
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.
One of the caller's own assignments, with where to collect it, what
is in it, where it goes and what to collect for it. Refused with
FOREIGN_ASSIGNMENT for another courier's.
Arguments
Get featured products (discounted or high display priority).
Optionally filtered by *product* category (menu section).
With location, only products of shops near it are returned — the
same shops the shops list would return for that location. Without
it, products from every shop of the business.
Arguments
Default
{
"limit": 10,
"page": 1,
"after": null
}The caller's own assignments: ACTIVE is what they carry, HISTORY
what they have delivered, failed or handed back within range — the
last thirty days when none is given — one page at a time.
Arguments
Default
{
"limit": 10,
"page": 1,
"after": null
}The cash the caller took on the deliveries they completed within
range, one row per currency, with how many deliveries they
completed in all and how many were paid in cash. Empty when they
completed none.
Arguments
The caller's own courier row: their team, vehicle, whether they are
on shift and what they carry. Refused with COURIER_NOT_INVITED when
no shop has put them on a team.
The caller's own shifts that started within range, newest first.
Arguments
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).
Arguments
Low-stock and out-of-stock counts for one of the current merchant's shops — powers the vendor home "needs restock" summary.
Arguments
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.
Arguments
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.
Arguments
Default
{
"limit": 10,
"page": 1,
"after": null
}Get shops owned by the current merchant.
Arguments
Sales chart (revenue + order count per bucket) for one of the current
merchant's shops. Scoped to shop_id after verifying ownership; currency is
the merchant's own currency. bucket sets what one point covers — a week
unless asked otherwise. Optional date range narrows the window.
Arguments
Default
"WEEK"Get a product by ID.
Arguments
Get all availability schedule entries for a product.
Arguments
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
Arguments
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.
Arguments
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).
Arguments
Get all shop categories. Returns enabled categories sorted by display order.
Get a shop category by ID.
Arguments
The couriers on one of the caller's shops' team, newest first, and
with includePool the workspace pool after them: everyone a delivery
from that shop can be handed to. Pool rows are read-only for a shop.
Arguments
Default
falseList delivery zones for a specific shop (admin).
Arguments
Default
{
"limit": 10,
"page": 1,
"after": null
}Default
[]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.
Arguments
Deprecation reason: Use shopOrdersWithValues; BET-205
Arguments
Default
{
"limit": 10,
"page": 1,
"after": null
}Default
[]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.
Arguments
A named window ending now (e.g. `LAST7_DAYS`), resolved on the server — the same `MetricsPeriodInput` the analytics queries take. Use instead of `dateRangeStart` / `dateRangeEnd`.
Get orders for a specific shop owned by the current merchant. Supports filters, sorting, and pagination.
Arguments
Default
{
"limit": 10,
"page": 1,
"after": null
}Default
[]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.
Arguments
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.
Arguments
Default
{
"query": null,
"location": null,
"shopCategoryId": null,
"shopSubcategoryId": null,
"currentlyOpenOnly": null,
"minRating": null,
"maxDeliveryFee": null,
"hasDiscount": null,
"limit": 10,
"page": 1,
"after": null,
"sorting": []
}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.
Arguments
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.
Accept an incoming shop order.
Arguments
Add an item to the cart.
Arguments
Hand a delivery to a courier of its shop's team or of the workspace
pool, by hand, over the ranking or the shop's own choice. The courier
has to be active; they need not be on shift. Refused with
DELIVERY_ALREADY_ASSIGNED while a courier has the delivery.
Arguments
Start a shop under a Shop Merchant account. A retry with the same account and name returns the first shop instead of creating a duplicate.
Arguments
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),
and the variant and options chosen with it, exactly as addToCart does.
- Computes pricing: subtotal = sum of (unit_price + options) × 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.
Arguments
Grant a shop a badge, for a set time or with no end. A shop holds at most one badge of each kind, so granting one it already holds moves that badge's window instead of adding a second.
Arguments
Bring a courier onto a shop's team or into the workspace pool, by
phone. An account that signs in with the number is enrolled;
otherwise one is created for it. Inviting the same number to the
same team again updates the vehicle and the notes. Someone already a
courier elsewhere in the workspace is moved with
adminUpdateShopCourier, not invited again.
Arguments
Hand a delivery from the courier who has it to another, before
pickup, in one step: unlike releasing it and assigning again, the
ranking does not hand it to someone else in between. Refused with
NO_COURIER_ASSIGNED when nobody has it and COURIER_PICKED_UP once
they have the order; when the new courier cannot take it, the
delivery is sent for again as after a release, and the refusal is
returned. Answers the new courier's assignment.
Arguments
Take a delivery back from the courier it was handed to, before
pickup, for another to be found. Refused with COURIER_PICKED_UP
once the courier has the order; they deliver it or report it failed.
Arguments
Take a courier off the books, whichever team they are on. Their open shift is ended, every delivery they hold goes back to waiting for a courier, and their Shop Courier role is revoked.
Arguments
Take a badge away from a shop. Taking away one it does not hold is not an error: the shop ends up without it either way.
Arguments
Set what the workspace keeps of its shops' items, as a percentage between 0 and 100, or with no value go back to keeping nothing. Applies to orders settled from now on, and to every shop without a rate of its own. An order already settled is not settled again.
Arguments
Set how a shop hands deliveries to its own couriers and what they have to produce at the door. The proof applies to deliveries handed over from now on; one already in a courier's hands keeps the proof it was handed over with.
Arguments
Set the terms one shop sells on: its own commission, and the share of a courier's fee it pays. The commission applies to orders settled from now on. The share of the courier's fee applies to orders placed from now on: one already placed keeps the split its customer was quoted.
Arguments
Change a courier of the workspace: move them between a team and the pool, change what they ride or the notes about them, or suspend and reinstate them.
Arguments
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.
Enabling also requires the owning merchant to be approved.
Arguments
Approve a merchant (admin only). Sets merchant status to Approved and marks as verified.
Arguments
Hand one of the caller's shop orders to a courier of the shop's team
or of the workspace pool, by hand. The courier has to be active;
they need not be on shift. Refused with DELIVERY_ALREADY_ASSIGNED
while a courier has the delivery, and with ORDER_NOT_READY for an
order the shop has not accepted or has already handed over.
Arguments
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's expiresAt says how long it holds — call again once it has
passed.
A refusal the customer can act on carries extensions.code — one of
DELIVERY_ADDRESS_REQUIRED, OUT_OF_DELIVERY_AREA, MIN_ORDER_NOT_MET,
SHOP_CLOSED, SHOP_NOT_ACCEPTING_ORDERS, FULFILLMENT_NOT_SUPPORTED,
EXPRESS_DELIVERY_UNAVAILABLE — plus shop_id when it concerns one shop
and min_order_minor / currency for an unmet minimum.
Arguments
Clear all items from the cart.
The courier is at the customer's door.
Arguments
The courier has reached the shop. Refused with FOREIGN_ASSIGNMENT
for a delivery handed to someone else, and with ILLEGAL_TRANSITION
out of order. Reported again, it answers the same.
Arguments
The order is with the customer. What the shop asks for at the door
has to be produced: PIN_REQUIRED / WRONG_PIN (with
attemptsLeft) / PIN_LOCKED (with lockedUntil, an hour after the
fifth wrong PIN) for a shop asking for the customer's PIN,
PHOTO_REQUIRED for one asking for a photo. A cash order needs
cashCollected to the amount due (CASH_REQUIRED, CASH_MISMATCH,
both with amountDueMinor); a card order refuses it
(NOT_A_CASH_ORDER). Reported again once delivered, it answers the
same and changes nothing.
Arguments
The delivery could not be completed. The order goes back to the shop, which is told why; a delivery that failed before pickup is sent for another courier at once.
Arguments
The courier has the order and is leaving the shop. The order goes
on its way and the customer is told. Refused with ORDER_NOT_READY
while the shop is still preparing it.
Arguments
Create a delivery zone on a shop owned by the calling merchant.
Arguments
Create a new product.
Arguments
Create a new product category. Admins may target any shop of their workspace; merchants only their own shops.
Arguments
Create a new product option within a group.
Arguments
Create a new shop category. # Authorization Requires TenantAdmin or PlatformAdmin role.
Arguments
Create a new delivery zone for a shop.
Arguments
Delete a delivery zone — caller must own the shop it belongs to.
Arguments
Delete a product option.
Arguments
Delete a shop category by ID. # Authorization Requires TenantAdmin or PlatformAdmin role.
Arguments
Delete a delivery zone.
Arguments
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.
Arguments
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.
Arguments
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.
Arguments
Bring a courier onto one of the caller's shops' team, by phone. An account that signs in with the number is enrolled; otherwise one is created for it. Inviting the same number again updates the vehicle and the notes and returns the courier as they are. Someone already riding for another shop, or for the workspace pool, is refused: the workspace's staff move couriers between teams.
Arguments
Mark an order as delivered.
Arguments
Mark an order as picked up.
Arguments
Mark an order as ready for pickup/delivery.
Arguments
Reject a submitted vendor application. The vendor may correct it and submit again; their disabled onboarding shop stays off.
Arguments
Take one of the caller's shop orders back from the courier it was
handed to, before pickup, for another courier to be found: at once
for a shop that assigns automatically, by the shop for one that
picks by hand. Refused with COURIER_PICKED_UP once the courier has
the order; they deliver it or report it failed.
Arguments
Remove an item from the cart.
Arguments
Take a courier off one of the caller's shops' team. Their open shift is ended, every delivery they hold goes back to waiting for a courier, and their Shop Courier role is revoked.
Arguments
Reorder options within a group.
Arguments
Arguments
Set the delivery address for the cart. Only requires the saved location ID — coordinates are resolved server-side from the identity service.
Arguments
Set the delivery mode for the cart.
Arguments
Go on shift (on: true) or off it. On shift, the courier is handed
deliveries and their app reports where they are; a shift stays open
until they go off, the shop ends it, or their app stops reporting
for three minutes. Asking for the state they are already in changes
nothing. A suspended courier is refused.
Arguments
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).
Arguments
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.
Arguments
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.
Arguments
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.
Arguments
Set operating hours for a shop (bulk replace all days).
Arguments
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.
Arguments
Start preparing an order.
Arguments
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.
Take a delivery over: the shop delivers the order itself instead of a courier. The way out for an order no courier could be found for, which would otherwise sit ready with nobody coming. An express delivery becomes a shop delivery from here on — sent for delivery, then delivered, by the shop — and any search for a courier still running is called off. A delivery by the shop's own riders stops waiting for one; a rider handed it and not yet at pickup is taken off it. Refused once a courier has the goods.
Arguments
Toggle product availability.
Arguments
Toggle a product option's enabled state.
Arguments
Toggle shop open/closed state.
Arguments
Update item quantity in cart.
Arguments
Report where the courier is. Refused with COURIER_NOT_ON_SHIFT
while they are not on shift. The customer and the shop of every
delivery in hand are told, with an estimate of the courier's arrival.
Arguments
Update a delivery zone — caller must own the shop the zone lives on.
Arguments
Arguments
Update an existing product category.
Arguments
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.
Arguments
Update an existing product option.
Arguments
Update product status (draft, active, discontinued).
Arguments
Update an existing shop.
Arguments
Update an existing shop category. # Authorization Requires TenantAdmin or PlatformAdmin role.
Arguments
Change a courier of one of the caller's shops: what they ride, the notes about them, or whether they are handed deliveries.
Arguments
Update an existing delivery zone.
Arguments
Subscribe to a shop courier's events (Shop service)
Receive real-time events for the courier's own deliveries:
- A delivery assigned to you
- A delivery taken back from you
- Your shift being closed by the shop
- Notifications
**Requirements:**
- Must be authenticated
- Must have Courier role
- Must be using Shop app
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
Deprecation reason: Use shopCustomerEventStream; BET-205
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
Deprecation reason: Use shopVendorEventStream; BET-205
BetterSuite is built for teams who see on-demand as a business — not a feature.