Skip to content

SLO API

Build against the canonical SLO REST API, then use the agent endpoint when tool-call semantics are a better fit. Both surfaces share the same underlying application logic.

What can you do with it?

The REST API under /api/* is the long-term contract for shop automation and integrations. The agent endpoint is an adapter for tool-based clients, not a separate business-logic surface.

Products

Create, update, and remove products. Set prices, descriptions, and inventory — all at once or one at a time.

Orders

See incoming orders, confirm or cancel them, update fulfillment status as you pack and deliver.

Inventory

Update stock levels globally or per channel. Keep availability in sync without manual entry.

Channels

List your sales channels — delivery, pickup, wholesale — and manage which ones are active.

Start with REST when you want stable resource-oriented contracts. Use the agent endpoint when you want the same capabilities exposed as tool calls.

Quick start

1

Get an API key

Shop admin → Apps → Create Key. Copy it — shown once.

2

Call the canonical REST API

curl -X GET 'https://slo.earth/api/channels?shopId=shop_123' \
  -H "Authorization: Bearer sk_live_..."
3

Use the agent adapter when needed

curl -X POST https://slo.earth/api/agent \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"tool":"listProducts"}'
4

Get structured data back

{
  "ok": true,
  "result": {
    "products": [...],
    "total": 12
  }
}

Endpoints

Canonical REST API
GET/POST https://slo.earth/api/*

Agent adapter
POST https://slo.earth/api/agent

Authorization: Bearer sk_live_...

REST example

GET /api/channels?shopId=shop_123

POST /api/channels
{
  "action": "create",
  "shopId": "shop_123",
  "title": "Wholesale"
}

Agent example

POST /api/agent
{
  "tool": "createChannel",
  "params": { "title": "Wholesale" }
}

Mutation response

{
  "success": true,
  "requestId": "req_123",
  "replayed": false
}

Error

{
  "error": "Forbidden",
  "requestId": "req_123"
}

Authentication

Use a bearer token in the Authorization header. Each key is scoped to one shop and can be revoked at any time. For mutating requests, you can also send Idempotency-Key and X-Request-Id.

Authorization: Bearer sk_live_your_key_here
Idempotency-Key: optional-but-recommended-for-mutations
X-Request-Id: optional-client-request-id

Tools

products

listProducts

List products for your shop. Use the 'search' param to filter by name/variety when looking for specific products — avoids returning the full catalog.

Params

limitnumber— Max products to return
offsetnumber— Number of products to skip
searchstring— Filter by title or variety (case-insensitive)
{
  "tool": "listProducts",
  "params": {}
}

→ { products: Product[], total: number }

getProduct

Get a single product by ID

Params

productIdstringrequired— The product _id
{
  "tool": "getProduct",
  "params": {
    "productId": "product_abc123"
  }
}

→ { product: Product }

createProduct

Create a new product

Params

titlestringrequired— Product title
descriptionstring— Product description
pricenumber— Base price per kg/L/piece in SEK (NOT per selling unit — the system calculates per-unit price)
inventoryTypestring— How inventory is tracked: "weight" (bulk kg), "volume" (bulk L), or "piece" (counted items). Default: weight
unitTypestring— What the customer buys: "weight", "volume", or "item". For bulk: matches inventoryType. For pre-packaged: "piece" inventory + "weight"/"volume" unitType
unitnumber— Selling unit size in g/mL. Default 1000 (=1kg or 1L). Examples: 10000 for 10kg batch, 500 for 500g bag
unitStepnumber— Minimum order increment. For bulk weight/volume: 0.1 = customer can order in 100g/100mL steps. For piece: 1 = one at a time
varietystring— Product variety/cultivar (e.g. "King Edward", "Roma")
hideFromStorefrontboolean— Hide from public storefront
taxnumber— Tax rate as decimal (e.g. 0.12 for 12%)
hideFromCalendarboolean— Hide from harvest calendar
transportCategorystring— Temperature zone for delivery: "frozen", "refrigerated", or "roomTemperature" (default)
{
  "tool": "createProduct",
  "params": {
    "title": "Organic Tomatoes"
  }
}

→ { product: Product }

updateProduct

Update an existing product. Only send fields you want to change.

Params

productIdstringrequired— The product _id
titlestring— Product title
varietystring— Product variety/cultivar (e.g. "King Edward", "Roma")
descriptionstring— Product description
pricenumber— Base price per kg/L/piece in SEK (NOT per selling unit — the system calculates per-unit price)
inventoryTypestring— How inventory is tracked: "weight" (bulk kg), "volume" (bulk L), or "piece" (counted items)
unitTypestring— What the customer buys: "weight", "volume", or "item". For bulk: matches inventoryType. For pre-packaged: "piece" inventory + "weight"/"volume" unitType
unitnumber— Selling unit size in g/mL. Examples: 10000 for 10kg batch, 500 for 500g bag, 1000 for 1kg/1L
unitStepnumber— Minimum order increment. For bulk weight/volume: 0.1 = 100g/100mL steps. For piece: 1 = one at a time
hideFromStorefrontboolean— Hide from public storefront
taxnumber— Tax rate as decimal (e.g. 0.12 for 12%)
hideFromCalendarboolean— Hide from harvest calendar
channelPricesstring— JSON array of channel price overrides, e.g. [{"channelId":"abc","price":50}]
channelInventorystring— JSON array of channel inventory overrides, e.g. [{"channelId":"abc","available":10}]
channelUnitsstring— JSON array of channel unit overrides, e.g. [{"channelId":"abc","unit":500,"unitStep":0.1}]
harvestStartstring— Harvest start date (YYYY-MM-DD)
harvestEndstring— Harvest end date (YYYY-MM-DD)
transportCategorystring— Temperature zone for delivery: "frozen", "refrigerated", or "roomTemperature" (default)
{
  "tool": "updateProduct",
  "params": {
    "productId": "product_abc123"
  }
}

→ { product: Product }

batchUpdateProducts

Update multiple products at once. Send a JSON array of updates as a string.

Params

updatesstringrequired— JSON array of objects, each with productId and fields to update. Example: [{"productId":"abc","price":200},{"productId":"def","title":"New name"}]
{
  "tool": "batchUpdateProducts",
  "params": {
    "updates": "..."
  }
}

→ { results: { productId, ok, title?, error? }[] }

deleteProduct

Delete a product

Params

productIdstringrequired— The product _id
{
  "tool": "deleteProduct",
  "params": {
    "productId": "product_abc123"
  }
}

→ { deleted: true }

uploadProductImage

Set a product's primary image. IMPORTANT: When the user has attached an image in chat, ALWAYS use assetId from the attachment metadata — NEVER use imageBase64. The assetId is shown in the attachment info like 'Sanity asset ID: image-xxx'. Only use imageUrl for external URLs. Never generate or fabricate base64 data.

Params

productIdstringrequired— The product _id
assetIdstring— Sanity asset ID (e.g. 'image-abc123-1920x1080-jpg') from a user-uploaded attachment. Preferred when available.
imageUrlstring— Public HTTPS URL of the image
imageBase64string— Base64-encoded image data (e.g. from a user-uploaded file)
mimeTypestring— MIME type when using imageBase64 (e.g. "image/png", "image/jpeg"). Defaults to image/png.
{
  "tool": "uploadProductImage",
  "params": {
    "productId": "product_abc123"
  }
}

→ { success: boolean, assetRef: string, productId: string }

inventory

updateInventory

Update inventory for a product (global or per-channel)

Params

productIdstringrequired— The product _id
availablenumber— Available stock in display units: kg for weight, L for volume, count for piece (e.g. pass 2 for 2 kg, not 2000)
channelIdstring— Optional: update channel-specific inventory instead of global
{
  "tool": "updateInventory",
  "params": {
    "productId": "product_abc123"
  }
}

→ { product: Product }

batchUpdateInventory

Update inventory for multiple products in one call. More efficient than calling updateInventory multiple times.

Params

updatesstringrequired— JSON array: [{"productId":"...","available":10},{"productId":"...","available":25}]. Values in display units (kg/L/count).
{
  "tool": "batchUpdateInventory",
  "params": {
    "updates": "..."
  }
}

→ { results: { productId, title, variety, previousAvailable, newAvailable, unit, imageUrl }[] }

orders

listOrders

List orders for your shop

Params

dropIdstring— Filter by drop _id
statusstring— Filter by status
limitnumber— Max orders to return (default: 50)
offsetnumber— Number of orders to skip
{
  "tool": "listOrders",
  "params": {}
}

→ { orders: Order[], total: number }

getOrder

Get a single order by _id or order number

Params

orderIdstringrequired— The order _id or order number (e.g. '97')
{
  "tool": "getOrder",
  "params": {
    "orderId": "order_abc123"
  }
}

→ { order: Order }

updateOrderStatus

Update the status of an order

Params

orderIdstringrequired— The order _id or order number (e.g. '97')
statusstringrequired— New status (e.g. "confirmed", "delivered", "cancelled")
{
  "tool": "updateOrderStatus",
  "params": {
    "orderId": "order_abc123",
    "status": "active"
  }
}

→ { order: Order }

confirmOrder

Confirm a pending order. Sets correct status based on payment type (invoice → confirmedInvoice, swish → paid), sets fulfillment to packing, and notifies the buyer.

Params

orderIdstringrequired— The order _id or order number (e.g. '97')
notifyBuyerboolean— Set to false to skip buyer notifications for this action.
{
  "tool": "confirmOrder",
  "params": {
    "orderId": "order_abc123"
  }
}

→ { order: Order }

cancelOrder

Cancel an order. Refunds inventory and notifies the buyer.

Params

orderIdstringrequired— The order _id or order number (e.g. '97')
cancelledBystring— Who initiated the cancellation: "buyer" or "seller". Defaults to "seller".
notifyBuyerboolean— Set to false to skip buyer notifications for this action.
{
  "tool": "cancelOrder",
  "params": {
    "orderId": "order_abc123"
  }
}

→ { success: true }

updateFulfillment

Update order fulfillment status. Valid statuses: packing, ready, inTransit, delivered. Notifies the buyer on status change.

Params

orderIdstringrequired— The order _id or order number (e.g. '97')
statusstringrequired— New fulfillment status: packing, ready, inTransit, or delivered
notifyBuyerboolean— Set to false to skip buyer notifications for this action.
{
  "tool": "updateFulfillment",
  "params": {
    "orderId": "order_abc123",
    "status": "active"
  }
}

→ { order: Order }

editOrderItems

Edit item prices/quantities and/or remove items from an existing order. Quantities are in display units. Inventory is auto-adjusted for pending orders.

Params

orderIdstringrequired— The order _id or order number (e.g. '97')
editsstring— JSON array: [{"itemKey":"...","price":75,"quantity":2}]. Include only fields to change.
removalsstring— JSON array of item _key strings to remove: ["key1","key2"]
notifyBuyerboolean— Set to false to skip buyer notifications for this action.
{
  "tool": "editOrderItems",
  "params": {
    "orderId": "order_abc123"
  }
}

→ { order: Order }

addOrderItems

Add one or more products to an existing order. Quantities in display units (kg/L/count). Inventory is auto-adjusted.

Params

orderIdstringrequired— The order _id or order number (e.g. '97')
itemsstringrequired— JSON array: [{"productId":"...","quantity":2}]. Quantity in display units.
notifyBuyerboolean— Set to false to skip buyer notifications for this action.
{
  "tool": "addOrderItems",
  "params": {
    "orderId": "order_abc123",
    "items": "..."
  }
}

→ { order: Order }

addOrderItemsFromCart

Append one or more pre-built order items to an existing order. Use this when the items were already constructed by the cart builder.

Params

orderIdstringrequired— The order _id or order number (e.g. '97')
itemsarrayrequired— Array of pre-built OrderItem objects to append.
notifyBuyerboolean— Set to false to skip buyer notifications for this action.
{
  "tool": "addOrderItemsFromCart",
  "params": {
    "orderId": "order_abc123",
    "items": []
  }
}

→ { order: Order }

updateDeliveryPrice

Update the delivery/pickup price on an existing order. Pass the new ex-VAT price. Tax summary auto-recalculates.

Params

orderIdstringrequired— The order _id or order number (e.g. '97')
deliveryPricenumberrequired— New delivery price (ex-VAT). Use 0 for free delivery.
notifyBuyerboolean— Set to false to skip buyer notifications for this action.
{
  "tool": "updateDeliveryPrice",
  "params": {
    "orderId": "order_abc123",
    "deliveryPrice": 10
  }
}

→ { order: Order }

capturePayment

Capture a Stripe payment for an uncaptured order, mark it paid, and move fulfillment to packing.

Params

orderIdstringrequired— The order _id or order number (e.g. '97')
notifyBuyerboolean— Set to false to skip buyer notifications for this action.
{
  "tool": "capturePayment",
  "params": {
    "orderId": "order_abc123"
  }
}

→ { order: Order }

cancelPayment

Cancel a Stripe payment and mark the order as cancelled.

Params

orderIdstringrequired— The order _id or order number (e.g. '97')
{
  "tool": "cancelPayment",
  "params": {
    "orderId": "order_abc123"
  }
}

→ { success: true }

createOrder

Create an order. Known buyers (entityId) get a finalized order immediately (inventory overdraft is allowed — the seller already confirmed via estimate). Unknown buyers (email only) get a draft with an invitation. If finalization fails, the order is saved as a visible draft for admin review.

Params

channelIdstringrequired— Channel _id
dropIdstringrequired— Drop _id
itemsstringrequired— JSON array: [{"productId":"...","quantity":2}]. Quantity in display units: kg for weight, L for volume, count for pieces.
entityIdstring— Buyer entity _id (known buyer)
emailstring— Buyer email — only use when admin explicitly provides it. NEVER fabricate or guess an email. Prefer entityId from listCustomers.
buyerNamestring— Display name (used in invite flow)
sendInvitationboolean— Send invitation email for unknown buyer (default: false — must be explicitly set to true only after admin confirms)
deliveryPricenumber— Custom delivery price (0 for free). Omit for channel default.
draftOnlyboolean— Save as draft without finalizing. REQUIRED when creating orders from image/document parsing (handwritten forms, PDFs, Excel). The admin must review and finalize manually.
{
  "tool": "createOrder",
  "params": {
    "channelId": "channel_abc123",
    "dropId": "drop_abc123",
    "items": "..."
  }
}

→ { order: { orderId, orderNumber, status }, invitation?: { invitationId } }

estimateOrder

Compute order totals (items + delivery + grand total) without creating an order. Use this to show a breakdown before confirming. Returns stock availability per item — check hasOverstock and warn the user about insufficient inventory before proceeding.

Params

channelIdstringrequired— Channel _id
dropIdstringrequired— Drop _id
itemsstringrequired— JSON array: [{"productId":"...","quantity":2}]. Quantity in display units: kg for weight, L for volume, count for pieces.
entityIdstring— Buyer entity _id (for resolving buyer name)
deliveryPricenumber— Custom delivery price (0 for free). Omit for channel default.
{
  "tool": "estimateOrder",
  "params": {
    "channelId": "channel_abc123",
    "dropId": "drop_abc123",
    "items": "..."
  }
}

→ { estimate: { buyerName, channel, items: [{ ..., availableStock, requestedStock, overstock }], subtotal, delivery, deliveryOverridden, grandTotal, currency, taxType, hasOverstock } }

channels

listChannels

List all channels for your shop

{
  "tool": "listChannels"
}

→ { channels: Channel[] }

getChannel

Get a single channel by ID

Params

channelIdstringrequired— The channel _id
{
  "tool": "getChannel",
  "params": {
    "channelId": "channel_abc123"
  }
}

→ { channel: Channel }

createChannel

Create a new sales channel

Params

titlestringrequired— Channel title
privacystring— "public" or "private" (default: public)
paymentsstring— Payment method: "invoice", "manual_invoice", "swish", or "card"
deliveryTypestring— "delivery" or "pickup"
deliveryPricenumber— Delivery fee
{
  "tool": "createChannel",
  "params": {
    "title": "Organic Tomatoes"
  }
}

→ { channel: Channel }

updateChannel

Update a channel. Only send fields you want to change.

Params

channelIdstringrequired— The channel _id
titlestring— Channel title
privacystring— "public" or "private"
paymentsstring— Payment method
deliveryTypestring— "delivery" or "pickup"
deliveryPricenumber— Delivery fee
{
  "tool": "updateChannel",
  "params": {
    "channelId": "channel_abc123"
  }
}

→ { channel: Channel }

deleteChannel

Delete a channel. Fails if drops reference this channel.

Params

channelIdstringrequired— The channel _id
{
  "tool": "deleteChannel",
  "params": {
    "channelId": "channel_abc123"
  }
}

→ { deleted: true }

shop

getShop

Get your shop details

{
  "tool": "getShop"
}

→ { shop: Shop }

updateShopProfile

Update the shop's public profile. Only send fields you want to change: title, description, contact info, social links, certifications.

Params

titlestring— Shop title (1-100 chars)
descriptionstring— Shop description
contactPersonstring— Contact person name
contactPhonestring— Contact phone number
contactEmailstring— Contact email address
instagramstring— Instagram URL
facebookstring— Facebook URL
websitestring— Website URL
certDemeterboolean— Demeter certification
certKravboolean— KRAV certification
certOrganicboolean— EU organic certification
certBiosuisseboolean— Bio Suisse certification
certAbboolean— AB (Agriculture Biologique) certification
certOtherstring— Other certification (free text)
{
  "tool": "updateShopProfile",
  "params": {}
}

→ { success: true }

updateShopLocalisation

Update shop localisation settings: language, country, currency, tax rate and mode. Only send fields you want to change.

Params

languagestring— Shop language: 'en' or 'sv'
countrystring— Country code (e.g. 'SE', 'DK')
currencystring— Currency: 'sek', 'dkk', 'eur', or 'usd'
taxnumber— Default tax rate as decimal (e.g. 0.12 for 12%)
taxModestring— Tax mode: 'manual' or 'country_rules'
{
  "tool": "updateShopLocalisation",
  "params": {}
}

→ { success: true, language?: string }

updateShopSlug

Change the shop's URL handle (slo.earth/<handle>). Must be unique, lowercase letters/numbers/hyphens only.

Params

slugstringrequired— New URL handle (e.g. 'nibble-farm')
{
  "tool": "updateShopSlug",
  "params": {
    "slug": "..."
  }
}

→ { success: true, slug: string }

togglePickup

Enable or disable pickup at the shop's physical address.

Params

enabledbooleanrequired— true to enable pickup, false to disable
{
  "tool": "togglePickup",
  "params": {
    "enabled": false
  }
}

→ { success: true, pickupEnabled: boolean }

updatePhysicalStore

Configure the shop's physical store walk-in opening hours and Google sync. Opening hours is display-only metadata (the farm-shop walk-in story); online ordering windows are configured separately via order schedules. Opening hours is an array of 7 objects (day 0=Monday to 6=Sunday) with open/close times and closed flag.

Params

enabledbooleanrequired— Enable/disable physical store
openingHoursarrayrequired— Array of {day:0-6, open:'HH:MM', close:'HH:MM', closed:boolean}
googleSyncEnabledboolean— Enable Google Maps hours sync
{
  "tool": "updatePhysicalStore",
  "params": {
    "enabled": false,
    "openingHours": []
  }
}

→ { success: true }

updateShopColors

Update the shop's brand colors. Only send colors you want to change. Values should be valid CSS color values (hex, rgb, etc.).

Params

bgstring— Background color (e.g. '#ffffff')
fgstring— Foreground/text color (e.g. '#1a1a1a')
secondarystring— Secondary text color
accentstring— Accent/brand color
{
  "tool": "updateShopColors",
  "params": {}
}

→ { success: true }

updateSwishConfig

Configure Swish payment (Swedish mobile payment). Set the Swish phone number and company name.

Params

phonestringrequired— Swish phone number (Swedish format, e.g. '0701234567' or '1231234567')
companystringrequired— Company name shown to payers
{
  "tool": "updateSwishConfig",
  "params": {
    "phone": "...",
    "company": "..."
  }
}

→ { success: true }

publishShop

Publish or unpublish the shop

Params

publishbooleanrequired— true to publish, false to unpublish
{
  "tool": "publishShop",
  "params": {
    "publish": false
  }
}

→ { shop: Shop }

createOrderSchedule

Create an order schedule (producer-facing: 'schedule'). Restricts when customers can order and which delivery methods / pickup options apply. Multiple schedules coexist for parallel sales streams. Provide a TimeWindow for `timeWindow` (when buyers can order) and `deliveryTimeWindow` (when fulfillment happens).

Params

titlestring— Optional producer-facing name, e.g. 'Restaurant week'. If omitted, the UI auto-labels the schedule from its contents.
timeWindowobject— TimeWindow tagged union: { kind: 'anytime' } | { kind: 'recurring', rrule, durationDays, hours, interval?, offsetDays? } | { kind: 'oneoff', start, end, hours }.
deliveryTimeWindowobject— TimeWindow for fulfillment timing.
timeWindowExceptionsarray— Per-date overrides: [{ date, action: 'skip'|'open'|'note', note?, overrideHours?, overrideDates? }].
appliesToStorefrontboolean— Schedule applies to consumer (storefront) buyers.
appliesToWholesaleboolean— Schedule applies to wholesale (B2B) buyers.
channelIdsarray— Channel _id[] — which lists this applies to. Omit or empty = applies to all lists.
deliveryMethodIdsarray— Delivery method _id[] offered by this schedule.
pickupOptionIdsarray— Pickup option _id[] offered by this schedule.
prepLeadDaysnumber— Business days between order and earliest bookable slot. Default 0.
sortOrdernumber— Display order (lower = earlier). Optional.
{
  "tool": "createOrderSchedule",
  "params": {}
}

→ { orderSchedule: OrderSchedule }

updateOrderSchedule

Update an order schedule. Only include the fields you want to change. Arrays (channelIds, deliveryMethodIds, pickupOptionIds) replace the stored list when provided. timeWindow / deliveryTimeWindow are full TimeWindow objects.

Params

orderScheduleIdstringrequired— The orderSchedule _id
titlestring— New title
timeWindowobject— Replacement TimeWindow for the order side.
deliveryTimeWindowobject— Replacement TimeWindow for delivery.
timeWindowExceptionsarray— Replacement exception list.
appliesToStorefrontboolean— Schedule applies to storefront buyers.
appliesToWholesaleboolean— Schedule applies to wholesale buyers.
channelIdsarray— Replaces channels. Empty array = applies to all lists.
deliveryMethodIdsarray— Replaces delivery methods.
pickupOptionIdsarray— Replaces pickup options.
prepLeadDaysnumber— Business days between order and earliest bookable slot.
sortOrdernumber— Display order (number) or null to clear.
{
  "tool": "updateOrderSchedule",
  "params": {
    "orderScheduleId": "..."
  }
}

→ { orderSchedule: OrderSchedule }

delivery

createDeliveryMethod

Create a shop-global delivery method (delivery area + schedule + pricing). Drops filter which of these methods' slots to offer — they do not own delivery config.

Params

titlestringrequired— Method title, e.g. 'Söder delivery'
geoAreaLabelstringrequired— Free-form area label, e.g. 'Söder', 'Stockholm inner city'
descriptionstring— Optional description shown to buyers
b2cPricenumber— Fee (incl. VAT) for b2c buyers — what the private customer pays. Omit if not offered to b2c.
b2cFreeOvernumber— Free delivery for b2c when order total (incl. VAT) >= this amount
b2bPricenumber— Fee (excl. VAT) for b2b buyers. Omit if not offered to b2b.
b2bFreeOvernumber— Free delivery for b2b when order total (excl. VAT) >= this amount
recurrencestring— RRULE, e.g. 'FREQ=WEEKLY;BYDAY=TH'. Omit for one-off.
defaultCapacitynumber— Default max orders per slot (integer). Omit for unlimited.
{
  "tool": "createDeliveryMethod",
  "params": {
    "title": "Organic Tomatoes",
    "geoAreaLabel": "..."
  }
}

→ { deliveryMethod: DeliveryMethod }

updateDeliveryMethod

Update a shop-global delivery method. Only send fields you want to change.

Params

deliveryMethodIdstringrequired— The deliveryMethod _id
titlestring— Method title
geoAreaLabelstring— Free-form area label
descriptionstring— Description shown to buyers
b2cPricenumber— Fee (incl. VAT) for b2c buyers — what the private customer pays
b2cFreeOvernumber— Free delivery for b2c when order total (incl. VAT) >= this amount
b2bPricenumber— Fee (excl. VAT) for b2b buyers
b2bFreeOvernumber— Free delivery for b2b when order total (excl. VAT) >= this amount
recurrencestring— RRULE (e.g. 'FREQ=WEEKLY;BYDAY=TH')
defaultCapacitynumber— Default max orders per slot
{
  "tool": "updateDeliveryMethod",
  "params": {
    "deliveryMethodId": "..."
  }
}

→ { deliveryMethod: DeliveryMethod }

archiveDeliveryMethod

Soft-delete a delivery method (archived = true). Existing slots and historical orders keep resolving; the method is hidden from new bookings.

Params

deliveryMethodIdstringrequired— The deliveryMethod _id
{
  "tool": "archiveDeliveryMethod",
  "params": {
    "deliveryMethodId": "..."
  }
}

→ { archived: true }

pickup

createPickupOption

Create a shop-global pickup option (location + schedule + pricing). Independent of shop.physicalStore. Drops filter which of these options' slots to offer.

Params

titlestringrequired— Pickup option title, e.g. 'LIVS Söder'
locationobjectrequired— Address object { street, city, postalCode, country, placeId?, lat?, lng?, ... }
descriptionstring— Optional description shown to buyers
b2cPricenumber— Fee (incl. VAT) for b2c buyers — what the private customer pays. Typically 0. Omit if not offered to b2c.
b2cFreeOvernumber— Free over threshold (incl. VAT)
b2bPricenumber— Fee (excl. VAT) for b2b buyers. Omit if not offered to b2b.
b2bFreeOvernumber— Free over threshold (excl. VAT)
recurrencestring— RRULE (e.g. 'FREQ=WEEKLY;BYDAY=TH,SA;BYHOUR=15')
defaultCapacitynumber— Default max orders per slot
{
  "tool": "createPickupOption",
  "params": {
    "title": "Organic Tomatoes",
    "location": {}
  }
}

→ { pickupOption: PickupOption }

updatePickupOption

Update a shop-global pickup option. Only send fields you want to change.

Params

pickupOptionIdstringrequired— The pickupOption _id
titlestring— Pickup option title
locationobject— Address object
descriptionstring— Description shown to buyers
b2cPricenumber— Fee (incl. VAT) for b2c buyers — what the private customer pays
b2cFreeOvernumber— Free over threshold (incl. VAT)
b2bPricenumber— Fee (excl. VAT) for b2b buyers
b2bFreeOvernumber— Free over threshold (excl. VAT)
recurrencestring— RRULE
defaultCapacitynumber— Default max orders per slot
{
  "tool": "updatePickupOption",
  "params": {
    "pickupOptionId": "..."
  }
}

→ { pickupOption: PickupOption }

archivePickupOption

Soft-delete a pickup option. Existing slots and historical orders keep resolving; hidden from new bookings.

Params

pickupOptionIdstringrequired— The pickupOption _id
{
  "tool": "archivePickupOption",
  "params": {
    "pickupOptionId": "..."
  }
}

→ { archived: true }

slots

addSlotException

Add an exception to a delivery method's or pickup option's calendar on a specific date — 'skip' (hide a recurrence occurrence), 'added' (add an extra occurrence), or adjust capacityOverride / notes. Materializes the slot doc if needed.

Params

methodOrOptionIdstringrequired— The deliveryMethod or pickupOption _id
kindstringrequired— 'dm' for delivery method, 'po' for pickup option
datestringrequired— ISO date or datetime of the occurrence (e.g. '2026-05-07' or '2026-05-07T15:00:00Z')
actionstring— 'skip' to hide, 'added' for an ad-hoc occurrence outside the recurrence. Omit to only patch capacity/notes.
capacityOverridenumber— Override the method/option defaultCapacity for this specific slot. Integer >= 0.
notesstring— Producer-facing free text (e.g. 'Use back entrance, buzz #3')
{
  "tool": "addSlotException",
  "params": {
    "methodOrOptionId": "...",
    "kind": "...",
    "date": "..."
  }
}

→ { slot: Slot }

removeSlotException

Remove a slot exception. Fails if orders are already booked in the slot. If safe, the slot doc is deleted and any recurrence occurrence reappears automatically.

Params

slotIdstringrequired— The slot _id (format: 'slot.dm|po.<methodOrOptionId>.<YYYY-MM-DD>')
{
  "tool": "removeSlotException",
  "params": {
    "slotId": "..."
  }
}

→ { removed: true }

customers

listCustomers

List customers (buyers/followers) for your shop. Returns company name and channel membership for each buyer. Searches entity title, org name, and company name.

Params

searchstring— Search by name, company name, or email
limitnumber— Max results (default: 50)
{
  "tool": "listCustomers",
  "params": {}
}

→ { customers: Customer[] } // Each: { id, displayName, companyName, email, channels: [{_id, title}] }

updateFollowerChannels

Update which channels a buyer has access to

Params

entityIdstringrequired— Buyer entity _id
channelIdsarrayrequired— Array of channel _ids the buyer should have access to
{
  "tool": "updateFollowerChannels",
  "params": {
    "entityId": "...",
    "channelIds": [
      "channel_abc123"
    ]
  }
}

→ { updated: true }

inviteBuyer

Invite a buyer to follow your shop. ONLY call this after: 1) confirming the buyer is not already a follower (listCustomers), 2) the admin has provided the email, 3) you have read the email back and the admin confirmed it.

Params

emailstringrequired— Buyer email — must come from the admin, NEVER fabricated or guessed
channelIdsarray— Optional: array of private channel _ids to grant access to
{
  "tool": "inviteBuyer",
  "params": {
    "email": "..."
  }
}

→ { invitation: { invitationId } }

notifications

notifyFollowers

Send a push notification to all shop followers

Params

titlestringrequired— Notification title
bodystringrequired— Notification body text
{
  "tool": "notifyFollowers",
  "params": {
    "title": "Organic Tomatoes",
    "body": "..."
  }
}

→ { sent: true, count: number }

meta

listTools

List all available API tools and their parameters

{
  "tool": "listTools"
}

→ { tools: ToolDefinition[] }

reportTrainingFeedback

Log a training correction from the admin for the developer AI to process. Use when the admin corrects your response or teaches you a rule.

Params

userMessagestringrequired— The original user prompt that led to the incorrect response
aiResponsestringrequired— Brief summary of what you responded (the wrong/improvable answer)
correctionstringrequired— The admin's correction or instruction in their own words
categorystring— Classification: prompt-rule, tool-behavior, product-matching, tone, format, bug, or other
{
  "tool": "reportTrainingFeedback",
  "params": {
    "userMessage": "...",
    "aiResponse": "...",
    "correction": "..."
  }
}

→ { logged: true, id: string }

Errors

REST endpoints return HTTP status codes plus a stable JSON error shape. Mutations may include a requestId for tracing. The agent adapter returns the same underlying failures mapped into tool-call responses.

unauthorized

Invalid or revoked API key

forbidden

Key doesn't have permission for this tool

not_found

Resource doesn't exist, or unknown tool name

validation

Missing or invalid params

rate_limit

Too many requests — 60/min per key

internal

Something went wrong on our end

Rate limits

60 requests per minute per key. Check the response headers:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58
X-RateLimit-Reset: 1708617600

For agents

If you're an AI agent: call listTools first to discover every available operation and its parameter schema.

{ "tool": "listTools" }

The response includes name, description, category, params, and return shape — everything you need.