Skip to content

Shop ​

Shop is the commerce native app: catalog, orders, coupons, subscriptions, payments, delivery, and your public storefront. Install it under Team settings → Apps, then open Shop in the sidebar.

Overview ​

  • Manage products, services, coupons, and subscriptions
  • Create orders and quotes (catalog lines and custom lines)
  • Fulfill physical orders and handle returns
  • Connect payments, shipping, pickup, inventory, and kiosk
  • Run a public store on store.joai.ai
  • Agents get Shop MCP tools once the app is installed

In the app ​

Dashboard tabs ​

TabWhat you do
OrdersList/filter orders; status badge + Fulfill for pickup/shipping (stepper dialog); status dropdown for invoices; paid / outstanding / canceled revenue summary; commission agreements
ReturnsTeam Retouren list (order, customer, status, date); approve / reject / receive / refund; create from the order menu
ProductsProduct catalog (variations, media, tags, structured details, store listing)
ServicesBookable/sellable services (shared with Appointments)
CouponsDiscount codes (enable under Settings → Storefront first); list shows redemption count; open a coupon to see orders that used it
SubscriptionsMerchant view of customer subscriptions (cancel/resume)
TablesFood & drink teams only — open orders by table

Use Open store in the header to jump to the public storefront.

Catalog ​

  1. Open Shop → Products (or Services)
  2. Create items with prices, SKUs/variations, media, tags, and a tax rate (defaults to the team default from Settings → Tax)
  3. Toggle list on store / active vs hidden as needed
  4. On Services, drag rows to set the order shown in your storefront and booking page (or set order via API / agents)
  5. Set priceDisplay to from when the price is only a starting price (e.g. “ab 60 €”). Products with several distinct active variation prices show as from automatically; default is an exact price.
  6. Optional editor surfaces:
    • Variations (e.g. color / size types)
    • Volume pricing
    • Related products (kiosk upsells)
    • Product details — reusable sections shown on the storefront (nutrition tables, ingredients, specs, care instructions, etc.). Each section has a key, title, and either label/value rows (kv) or a text block (text). Titles and values can be translated.
    • Product configurator (warp-backed options when configured)
    • Booking details on services (same configurator; set it via settings.configurator on create_service / update_service; phone-named/labeled fields are saved on the CRM contact when customers book)
    • Stock per product/variation when inventory is on
    • Barcode per variation (EAN/GTIN/UPC or your own code, unique per team; product search matches it exactly)
    • External references per variation (link icon in the variations table): the article ID of the same item in a till/POS, ERP, marketplace, supplier, or other system. Each external ID is unique per team and source, and a variation can have several

Product sorting: GET /v1/products accepts an ordered sort list such as sort=availability:desc,name:asc. Fields: featured, name, price, availability; append :asc or :desc to override the field default (featured:desc, name:asc, price:asc, availability:desc). Multiple keys apply in order, so pagination stays stable. The legacy values price_asc, price_desc and name still work.

Volume pricing: add quantity tiers with a minimum quantity and unit price. The storefront product page and cart apply the highest reached tier, re-price the line when the quantity changes, and keep order lines/checkout on the same tier.

Product details live in meta.details on the product (API / MCP / warps). Example:

json
[
  {
    "key": "nutrition",
    "title": { "de": "Nährwerte", "en": "Nutrition" },
    "kind": "kv",
    "rows": [
      { "label": { "de": "Energie" }, "value": { "de": "350 kcal" } }
    ]
  },
  {
    "key": "ingredients",
    "title": { "de": "Zutaten" },
    "kind": "text",
    "text": { "de": "Maismehl, Wasser, Salz" }
  }
]

Pass details: [] (MCP) or nested meta.details: [] (API) to clear all sections. Warps send details via payload:meta.details. Tags: first tag is the category (Shop → Products filter + storefront category chips); further tags are labels (e.g. Vegan). Category options for the Products filter come from GET /v1/products/categories (categories + hasUntagged). The Products list also filters by stock (stock=out_of_stock|low_stock|in_stock|unlimited; low_stock uses the team threshold, default 5), active state (active=0|1), and sorts via sort=featured|name|price_asc|price_desc. Product and service lists are paginated (page / perPage, with meta.currentPage / meta.lastPage / meta.total). Pass all=1 for a single full-catalog response (capped).

Kiosk uses English lowercase product tags as categories — see the kiosk tag list.

Orders and quotes ​

Need a configurable client-facing scope before creating the quote? See Client proposals.

  1. Open Shop → Orders
  2. New order → pick a contact, add lines, optionally send confirmation
  3. Choose Order or Quote
  4. Optionally price as excl. VAT (net)
  5. For physical Orders, optionally set Fulfillment:
    • Pickup — choose an active location from Delivery settings
    • Shipping — pick a contact address and a rate from your shipping zones (quoted for that country/ZIP and line items). The contact needs an address first; configure zones under Shop → Settings → Delivery

The customer contact remains the buyer shown on the invoice. Use Invoice recipient during creation or editing when another contact (for example, an accounting inbox) should receive invoice and confirmation emails; leaving it at the default uses the customer contact.

Customer emails: Online checkout (card, Mollie, Stripe, …) sends the team-branded order confirmation only after payment. Offline / bank-transfer orders can confirm when placed, then send a payment-received note (with invoice) once paid. On a pending order, Notify contact runs joai-order-notify through the chosen agent (auto-approved sync execution) so a branded confirmation or payment reminder is sent as that agent. Agents can trigger the same warp from MCP (type: confirmation or payment-reminder). Each type can be sent once per hour per order.

Payment reminders: Opt in under Shop → Settings → Payments → Payment reminders. When enabled, unpaid pending shop orders (not quotes, marketplace purchases, or zero-total) get automatic customer emails on a payment-aware cadence — card/Mollie (and pickup with a reserved slot): 1 → 3 → 7 days; bank transfer / offline: 3 → 7 → 14 days — then stop. Already-old unpaid orders may get the first reminder soon after opt-in; later reminders still wait the full gap (not a same-day burst). Paying or canceling the order ends reminders. Manual payment reminders from the order menu count toward the same cap. Each reminder includes the invoice PDF when available (same as order confirmation), uses a guest pay link that works without login, and notifies active team members (push); the third/final reminder uses stronger “still unpaid — please follow up” copy.

Guest pickup checkout asks for a phone number so the shop can coordinate collection. Shipping checkout treats phone as optional. When a guest enters a phone, that number is stored on the matched CRM contact (by email) and is what Shop → Orders, fulfill dialogs, and board cards show. A later checkout with a different phone updates the contact. Leaving shipping phone empty does not clear a phone already on the contact. On order review, pickup checkouts let the customer pick an available Abholzeit from the team’s appointment calendar (same availability as /book). Placing the order books a real pickup appointment and embeds it on the order as meeting (with scheduledAt, timezone, status, …). That time appears on the customer confirmation email, the merchant order alert, and the delivery note. When Board (Planner) is installed, the order also creates a backlog item with notes, configurations, and the pickup deadline; fulfillment then moves that item forward only — Ready/Shipped → Review, Delivered → Done (never back from Done). After online payment, pickup and shipping orders are confirmed; they become delivered only when fulfillment or handover is completed.

Invoice and service orders without pickup/shipping stay pending until payment is recorded. Changing status to the closed state runs the paid path and shows as paid (not “delivered”). Pickup and shipping keep their fulfillment labels (“ready for pickup”, “picked up”, “delivered”).

For pickup (Abholung) and shipping, Shop → Orders stays calm: status badge plus a Fulfill action. The fulfill dialog walks payment → prepare → ready/shipped → collected/delivered with a packing checklist when marking ready or shipped, optional shipping tracking (carrier dropdown loaded from the API + tracking number; the API builds the carrier tracking link; after ship you can correct tracking in the same dialog; MCP create_fulfillment / update_fulfillment do the same from carrierCode + trackingNumber), and one primary button per step. Marking a shipping order shipped emails the customer with carrier, tracking number, and link when available. From the same dialog — and from the order menu / packing station on the order page — team managers can open a delivery note PDF (Lieferschein) via a signed URL — same visual language as invoices (logo, seller/customer blocks, footer), with order number, date, booked pickup appointment, customer contact, pickup place or shipping address, location instructions, physical line items with quantities, order notes, and handover signature lines — no prices, no customer number. Shipping orders also get a downloadable shipping label PDF (Versandetikett) — a compact 100×150 mm address label (from/to + order number). When marking shipped, merchants can opt in to open that label automatically (on by default). Weight and dimensions are not collected yet — they will appear when a carrier API needs them. Packing PDF links are merchant-only (not on guest order access). Carrier APIs are not required yet (manual logistics provider, swappable later). Agents can read shippingLabelUrl / deliveryNoteUrl from joai-order-get when acting as the team. Handoff (collected/delivered) only confirms — no re-checking items. Search orders by phone, order number, or name. Pickup-only shops use Neu / In Vorbereitung / Zur Abholung bereit / Abgeholt filters; mixed pickup+shipping lists use neutral Ready / Completed labels. The list shows time, phone, item quantities, and the concrete payment method (PayPal, card, bank transfer) when Mollie reports it. Mark ready for pickup on a paid order emails the customer (DE) with the order number, pickup place, and guest order link; the guest thank-you page shows the same pickup status through prepare → ready → picked up. Marking the fulfillment delivered sets the order to delivered (“picked up”) and emails the customer with the matching branded status email (delivered for shipping, collected for pickup). Cancelling an order emails the customer a branded cancellation notice, including pending and approved-but-unpaid orders; an optional cancellation reason from the cancel dialog is included when provided. Manual status jumps that skip steps are blocked; cancel remains available from the order menu.

Post-checkout return: Mark a brandless Sites record as type shop (with a public URL) so guest thank-you pages can send buyers back to that storefront. One shop site per team.

Line items:

TypeHow
Product / serviceFrom catalog (inherits the catalog item’s tax rate)
CustomDescription + quantity + unit price + optional tax rate (no catalog row)

Custom lines are for one-offs (repair, travel, materials). They appear on the order and invoice. Allowed only for authenticated team/agent create — not public checkout or kiosk. Mixed VAT (e.g. food vs drink) is handled per line via tax rates — not order-level tags.

Orders tab also surfaces order revenue stats (paid, outstanding, canceled/returned) and commission agreements where configured for the team.

Invoices and payment QR codes ​

Invoices show invoice date and service date (Leistungsdatum). Service date defaults to the invoice date when unset; set it when supply/service happened on a different day.

Pending invoices include payment instructions in the notes:

Team setupWhat appears
Bank only (IBAN/BIC set, payments.online off or unset)Bank transfer text + SEPA transfer QR (EUR) so customers can scan in their banking app
Online payments (payments.online on — requires payment setup)Pay link + link QR to the order page (bank text still shown if configured)

payments.online is opt-in: missing/unset means offline. The order number is always used as the payment reference in both the printed bank details and the SEPA QR. SEPA transfer QRs are EUR-only and skipped if the IBAN checksum is invalid. Paid invoices omit payment QR codes.

Fulfillment and returns ​

For physical pickup or shipping orders after payment:

  1. Open Fulfill on the order (list or order page)
  2. Check off items in the dialog, then use the primary action (ready for pickup / shipped, then collected / delivered)

Returns (Retoure): A customer can request a return once the order is paid and at least one physical item is on a shipped or delivered fulfillment (pickup counts after picked up). Eligibility is per item: only the shipped quantity not already in an open or completed return is offered. When items span multiple shipments, JoAi creates one return per fulfillment. The customer picks items and quantity and gives a reason — on the store order page, from Your orders (shown as Retoure beantragen), or on the order confirmation page (guests use the link from their email). The order page shows each return’s items, seller note, refund amount, and what to do next. A merchant can also open Create return from the order menu to log a return on the customer's behalf (reason, items, optional condition note); MCP create_return does the same and persists the return.

Shop → Returns lists all returns of the team with order, customer, reason, status, and date. Each return moves requested → approved → received → refunded, or can be rejected with an optional note for the customer. Approve, reject, receive, and refund use confirmation dialogs (not browser prompts). The customer is emailed when the return is requested, approved, rejected, received, and refunded. Refund amounts follow the returned line totals (including tax for net-priced orders) and are processed through the order’s payment provider when connected (e.g. Mollie). The same actions are available on the order row.

Invoice-only orders still use the status control (including paid when closed).

Settings ​

Shop → Settings:

TabUse for
GeneralCurrency, billing address, bank details for invoices, order notification emails
PaymentsOnline payments on/off; Stripe Connect / Mollie Connect; bank details
DeliveryShipping zones & rates; fulfillment / pickup locations
TaxVAT / tax rates for the catalog (default + reduced/special rates)
InventoryTeam-level stock tracking on/off and low stock threshold (default 5); then set stock on products/variations
StorefrontKiosk on/off; enable coupons; one-click reorder from order history (signed-in customers; unavailable lines are skipped); optional custom legal page URLs

Order notification emails (General): optional list of addresses (e.g. bestellung@shop.example) that receive a merchant alert when a shop order is placed — paid online orders after payment, bank/offline orders when created. Separate from customer confirmations and team seats.

Every public storefront gets built-in legal pages at /{locale}/{team}/legal/{terms|privacy|withdrawal|imprint}.

Automatic profile (no extra settings):

  1. Detect merchant country from invoice country → IBAN → timezone
  2. If EU/EEA/UK (or a generic Europe/* timezone) → built-in 14-day withdrawal notice
  3. Otherwise → built-in returns notice (no statutory withdrawal claim)

Country-specific statutes (FAGG, BGB, …) belong in custom legal URLs under Shop → Settings → Storefront when needed. Genuss and similar shops can host their own texts there.

Checkout shows the matching notice and requires acceptance of terms, withdrawal/returns, and privacy before a paid order.

Tax rates ​

Teams start with a default VAT rate. Add more rates (e.g. reduced food VAT) under Shop → Settings → Tax, then assign them on products, services, or custom order lines. Invoices and order accounting break tax down by rate. Agents manage the same rates via tax-class-list / tax-class-create / tax-class-update / tax-class-delete, and pass taxClassId on product/service create/update or custom order lines.

Delivery details ​

Shipping zones

  • Countries + optional postal-code rules
  • Active flag and sort position

Rates (per zone)

  • Price, free-shipping threshold, min/max order, weight limits, ETA days, active / position

Fulfillment locations

  • Pickup / ship-from address and customer-facing instructions

Per-product list on store controls catalog visibility — there is no single global “hide store” switch on Storefront beyond kiosk/coupons.

Connect a payment account under Payments before online pay works. You can disconnect and reconnect accounts from the same place.

Public surfaces ​

SurfaceWhere
Storehttps://store.joai.ai/{locale}/{team}
Kioskhttps://store.joai.ai/{locale}/{team}/kiosk
Booking (if Appointments)store book URL / Sites
Order / subscription portalPay; request returns (Retoure beantragen: items, qty, reason) once items are shipped or picked up; subscription skip / pause / resume delivery via portal (create_portal_session)

Full host map: Public surfaces.

For agents (MCP) ​

Requires Shop installed. Team tools are for merchants; customer tools are for buyer flows (different MCP audience).

Team (admin) ​

Shop admin UI and MCP tools require:

  1. Sign-in on the correct environment (production joai.ai, or DevNet devnet.joai.ai)
  2. An active team where you have TeamManage (Owner/Admin)
  3. Shop installed on that team (Team settings → Apps)

If those are missing, the UI shows a permission lock and APIs return 403.

ToolPurpose
create_product / update_product / delete_productProducts; create_product accepts stock, optional taxClassId, optional priceDisplay (exact / from), and optional details sections; update_product accepts optional details (pass [] to clear) and priceDisplay
create_product_variation / update_product_variationVariations; both accept stock (units available, null = unlimited) and barcode (unique per team; omit it to keep the current barcode, pass null to remove it on update)
add_product_variation_external_reference / update_product_variation_external_reference / remove_product_variation_external_referenceLink a variation to its article ID in another system (source: pos, erp, marketplace, supplier, other; externalId unique per team and source)
find_product_variationFind one variation by barcode, or by source + externalId (checked first, then the barcode)
create_service / update_service / delete_service / list_servicesServices (also with Appointments); create/update accept optional taxClassId, order (display sort, lower = earlier), priceDisplay (exact / from), and settings.configurator (booking detail fields; pass [] to disable)
tax-class-list / tax-class-create / tax-class-update / tax-class-deleteTeam VAT rates (list first to resolve taxClassId)
create_orderOrder or quote — catalog and/or custom lines; optional invoiceContactId; custom lines may pass taxClassId
update_orderStatus, dates, or invoice recipient; clear invoiceContactId to use the customer
notify_order (joai-order-notify)Send branded order confirmation to the customer contact as the executing agent (same path as Shop Notify contact)
list_orders / delete_orderList or delete orders (list_orders is paginated — use page / perPage, max 50, and read meta.lastPage for more); list_orders accepts couponId to show redemptions for a coupon
create_coupon / update_coupon / delete_coupon / list_couponsCoupons (list_coupons includes redemptionCount for team members)
create_fulfillment / update_fulfillment / list_fulfillmentsFulfillment
list_returns / update_returnReturns (merchant list and updates; also shown in Shop → Returns)

Shipping zones / fulfillment locations are configured in the UI (no dedicated MCP tools today).

Set stock on a variation to track units available: a positive number caps orders at the remaining units, 0 marks it out of stock, and null means unlimited stock. update_product and update_product_variation only change the fields you pass, so a partial update never clears price, stock, visibility, or media; pass stock: null explicitly to restore unlimited stock.

Custom line (unitPrice = cents; optional taxClassId from tax-class-list):

json
{
  "items": [
    {
      "type": "custom",
      "name": "On-site repair",
      "quantity": 1,
      "unitPrice": 8500,
      "taxClassId": "TAXCLASSHASH"
    }
  ]
}

Customer ​

ToolPurpose
list_productsBrowse catalog
place_checkout_order / create_checkout_snapshot / quote_checkout_shipping_ratesCheckout
list_checkout_fulfillment_locationsPickup / location options
pay_order / get_orderPay and inspect
create_returnStart a return (paid order, shipped/delivered items)
list_subscriptions / show_subscription / cancel_subscription / resume_subscriptionSubscriptions
list_addresses / store_addressAddresses
create_portal_sessionCustomer portal (including subscription delivery management)

Live schemas: tools/list. See MCP and SKILL.md.

Tips ​

  • Install Shop before expecting commerce MCP tools
  • Use custom lines for one-offs; catalog for repeatable sellables
  • Prefer contact find-or-create — never duplicate buyers
  • Pair Smart Links table QR with kiosk (?table= / lid=) — see Smart Links