taler-docs

073-extended-merchant-template.rst (15855B)

---

 DD 73: Extended Merchant Template
 #################################
 
 :Design status: Accepted
 :Implementation status: Partial
 :DD shepherd: TBD
 :Historical contributors: Bohdan Potuzhnyi
 :First published: 2025-11-04
 :Last substantive change: 2025-11-11
 :Implementation evidence: ``merchant`` (2025-11-15); backend and wallet protocol support landed, while merchant WebUI creation remains incomplete
 :Normative references: ``core/api-merchant.rst`` and ``core/merchant/get-templates-TEMPLATE_ID.rst``
 
 Summary
 =======
 
 `#0010234 <https://bugs.gnunet.org/view.php?id=10234>`__ targets a wallet-first shopping cart experience by extending the merchant
 template feature set with a dedicated inventory-driven template type. The new
 design keeps legacy fixed-order templates intact while enabling merchants to
 publish a single ``taler://pay-template`` QR code that lets the customer pick one
 or multiple inventory (product) entries directly inside the wallet.
 
 Motivation
 ==========
 
 The existing template API (see :ref:`Section 1.4.15 <merchant-template-api>` of
 the merchant manual and `LSD 0006 <https://lsd.gnunet.org/lsd0006/>`__)
 lets merchants pre-define mostly static contracts. Wallets can prompt the user
 for an amount or order summary, then instantiate an order without the merchant
 needing online infrastructure. This is valuable for:
 
 * Offline and low-connectivity points-of-sale where only the customer's device
   has network access.
 * Static Web sites that want to embed a payment link or QR code without running
   dynamic backend logic.
 * Donation flows where the payer sets the amount but contract metadata stays
   stable.
 
 However, the current model fails to cover micro-merchants who want to publish a
 small inventory, have the wallet enforce contract terms, and still avoid
 operating a PoS or e-commerce website. Today they would need one QR code per product or
 fall back to a free-form amount entry workflow, neither of which captures stock
 keeping, category-based selections, or cart validation.
 
 As such we see two new scenarios:
 
 1. Tiny shops, farmers' stands, and unattended kiosks want to publish a QR code
    next to the shelves so customers can scan once, add multiple items and get
    order that can be paid
 2. Vending machines that usually dispense only one product per transaction
    still benefit from exposing a catalogue in the wallet UI, but must constrain
    the customer to one selection to lower the integration costs.
 
 Another question that arises is how the wallet retrieves products efficiently.
 Ideally the entire inventory subset arrives in one response so that up to
 roughly 300-400 items can be listed without paginations. Backends already store
 image metadata, so the wallet should also be able to fetch product pictures on
 request instead of embedding them in the initial payload.
 
 Requirements
 ============
 
 * Introduce a template type system that distinguishes fixed-order templates from
   inventory-driven ones extending existing REST templates, and creates a base for
   new possible template types.
 * Define merchant-side configuration for product selection, supporting:
 
   * all inventory,
   * category-filtered subsets, and
   * explicitly enumerated product IDs; combinations must be merged without
     duplicates.
 * Describe wallet-side UX affordances for choosing exactly one product or
   multiple products, driven by a ``choose_one`` style flag.
 * Extend the public ``GET /templates/$TEMPLATE_ID`` response to surface type,
   product descriptors, selection rules, and customer-editable defaults.
 * Extend the template instantiation ``POST`` to carry the selected products and
   quantities, reusing the ``TemplateDetails`` object.
 * Preserve handling of legacy template types from protocol versions v13+;
   clients that do not support the new inventory-cart type must reject that
   type cleanly.
 
 Proposed Solution
 =================
 
 Schema extensions
 -----------------
 
 Add an endpoint that lets
 wallets download product images via ``GET
 /instances/$ID/products/$IMAGE_HASH/image``.
 
 Introduce template type discriminator so processing
 of the template can be done per template version.
 
 .. ts:def:: TemplateType
 
   type TemplateType = "fixed-order" | "inventory-cart";
 
 .. ts:def:: TemplateContractDetailsType
 
   type TemplateContractDetailsType =
     TemplateContractDetails | TemplateInventoryContractDetails;
 
 
 Extend ``TemplateAddDetails`` and ``TemplateDetails`` to advertise the new type and, when
 ``template_type`` equals ``"inventory-cart"``, nest the inventory-specific
 contract.
 
 .. ts:def:: TemplateAddDetails
 
     interface TemplateAddDetails {
 
       // Template ID to use.
       template_id: Slug;
 
       // Human-readable description for the template.
       template_description: string;
 
       // OTP device ID.
       // This parameter is optional.
       otp_id?: Slug;
 
       // Fixed contract information for orders created from
       // this template.
       template_contract: TemplateContractDetailsType;
 
       // Key-value pairs matching a subset of the
       // fields from ``template_contract`` that are
       // user-editable defaults for this template.
       // Since protocol **v13**.
       editable_defaults?: Object;
     }
 
 .. ts:def:: TemplateDetails
 
     interface TemplateDetails {
 
       // Fixed contract information for orders created from
       // this template.
       template_contract: TemplateContractDetailsType;
 
       // Future fields remain identical to the existing structure.
     }
 
 New contract type has next structure:
 
 .. ts:def:: TemplateInventoryContractDetails
 
     interface TemplateInventoryContractDetails {
 
         // Template type defaults to ``fixed-order`` when missing.
         // Must be either ``fixed-order`` or ``inventory-cart``.
         // This prescribes which template_contract structure is expected.
         // TemplateContractDetails for ``fixed-order``.
         // TemplateInventoryContractDetails for ``inventory-cart``.
         template_type?: TemplateType;
 
         // Human-readable summary for the template.
         summary?: string;
 
         // Requests the wallet to offer a tip entry UI. The backend
         // verifies that amount equals selected products + tip.
         request_tip?: boolean;
 
         // Time window to pay before the order expires unfulfilled.
         pay_duration: RelativeTime;
 
         // Selects all products from merchant inventory and overrides
         // selected_categories and selected_products.
         selected_all?: boolean;
 
         // All products from selected categories are included.
         selected_categories?: Integer[];
 
         // Explicit list of product IDs to include.
         selected_products?: string[];
 
         // When true the wallet must enforce single-selection behaviour.
         choose_one?: boolean;
     }
 
 Wallets that do not recognise ``"inventory-cart"`` continue to expect
 template-level fields such as ``minimum_age``.  They must reject the unknown
 template type cleanly instead of attempting to interpret it as a legacy
 template.
 
 The merchant simply saves id's of ``selected_categories``
 and ``selected_products``.
 
 ``choose_one`` dictates whether the wallet must restrict the user
 to a single product/quantity combination (``true``) or allow arbitrary
 combinations (``false``/absent).
 
 Merchant private API updates
 ----------------------------
 
 ``POST`` and ``PATCH`` on ``/private/templates`` accept new ``TemplateInventoryContractDetails``.
 
 SPA
 ----
 The SPA embeds the new configuration in template
 creation forms:
 
 * Adding support for different ``template_type``.
 * Some clever ``template_type`` detection can be introduced, e.g. if the merchant selects the products
   automatically changed from ``fixed-order`` to ``inventory-cart``. Manage products from order page can be re-used.
 * Inventory selector widgets emit the union of categories and explicit product
   selections.
 * Optional quantity limits and defaults map to ``item_limits`` and ``item_default``.
 
 
 Wallet discovery API
 --------------------
 
 Enhance the public ``GET /instances/$INSTANCE/templates/$TEMPLATE_ID`` response
 to include both the inventory configuration and the resolved product metadata,
 by using ``TemplateWalletContractPayload``.
 
 .. ts:def:: TemplateWalletContractPayload
 
   type TemplateWalletContractPayload =
     TemplateWalletContractDetails | TemplateInventoryContractDetailsWallet;
 
 .. ts:def:: TemplateWalletContractDetails
 
   type TemplateWalletContractDetails = TemplateContractDetails;
 
 ``TemplateWalletContractDetails`` is identical to the ``TemplateContractDetails``
 object defined in :ref:`merchant-template-api`. Changes relative to the current
 protocol are called out below.
 
 .. ts:def:: WalletTemplateDetails
 
   interface WalletTemplateDetails {
 
       // Hard-coded information about the contract terms
       // for this template.
       template_contract: TemplateWalletContractPayload;
 
       // Key-value pairs matching a subset of the
       // fields from template_contract that are
       // user-editable defaults for this template.
       // Since protocol v13.
       editable_defaults?: Object;
 
       // Only present when TemplateWalletContractPayload requires it.
       // Required currency for payments.  Useful if no
       // amount is specified in the template_contract
       // but the user should be required to pay in a
       // particular currency anyway.  Merchant backends
       // may reject requests if the template_contract
       // or editable_defaults do
       // specify an amount in a different currency.
       // This parameter is optional.
       // Since protocol v13.
       required_currency?: string;
   }
 
 
 ``TemplateInventoryContractDetailsWallet`` intentionally omits a fixed currency
 or minimum age to allow multi-currency product listings and leave age checks to
 per-product logic when available.
 
 .. ts:def:: TemplateInventoryContractDetailsWallet
 
    interface TemplateInventoryContractDetailsWallet {
 
      // Human-readable summary for the template.
      summary?: string;
 
      // Request the wallet to offer a tip entry UI.
      request_tip?: boolean;
 
      // Time the customer has to pay before the order expires unpaid.
      pay_duration: RelativeTime;
 
      // Information about the resolved products.
      inventory_payload?: WalletInventoryPayload;
    }
 
 .. ts:def:: WalletInventoryPayload
 
   interface WalletInventoryPayload {
     // Contains all products selected by the merchant.
     products: WalletInventoryProduct[];
 
     // Contains all categories referenced by the products.
     categories: WalletInventoryCategory[];
 
     // Contains all custom units referenced by the products.
     units: WalletInventoryUnit[];
   }
 
 The following structures mirror the protocol-v25 inventory payload so that the
 backend, SPA, and wallet share a single meaning for every field while keeping
 the inventory available in one response.
 
 .. ts:def:: WalletInventoryProduct
 
   interface WalletInventoryProduct {
     product_id: Slug;
     product_name: string;
     description: string;
     description_i18n?: { [lang_tag: string]: string };
     taxes?: Tax[];
     unit: Slug;
     unit_prices: Amount[];
     unit_allow_fraction: boolean;
     unit_precision_level: Integer;
     remaining_stock: DecimalQuantity;
     categories: Integer[];
     image_hash?: string;
   }
 
 .. ts:def:: WalletInventoryCategory
 
   interface WalletInventoryCategory {
     category_id: Integer;
     category_name: string;
     category_name_i18n?: { [lang_tag: string]: string };
   }
 
 .. ts:def:: WalletInventoryUnit
 
   interface WalletInventoryUnit {
     unit: Slug;
     unit_name_long: string;
     unit_name_long_i18n?: { [lang_tag: string]: string };
     unit_name_short: string;
     unit_name_short_i18n?: { [lang_tag: string]: string };
     unit_allow_fraction: boolean;
     unit_precision_level: Integer;
   }
 
 This design lets wallets download hundreds of objects in a single request and
 fetch images later via the shared ``GET
 /instances/$ID/products/$IMAGE_HASH/image`` endpoint.
 
 Inventory template responses MUST include the complete product subset in a
 single payload; QR-code driven flows remain manageable only when the referenced
 catalog fragment comfortably fits into one REST response. Merchants are expected
 to keep templates constrained to a practical number of products (tens, not
 thousands). If extreme use cases ever arise, pagination can be revisited.
 
 Template instantiation
 ----------------------
 
 Extend ``POST /instances/$INSTANCE/templates/$TEMPLATE_ID`` to support the
 `UsingTemplateCommonRequest` type.
 
 ``amount`` lets the wallet supply a precalculated total;
 backends recompute the authoritative order amount and reject mismatches.
 Wallets submit ``InventoryTemplateUseDetails`` to ``POST
 /instances/$INSTANCE/templates/$TEMPLATE_ID`` when the template advertises
 ``template_type`` = ``"inventory-cart"``. ``tip`` carries the customer-selected
 gratuity whenever the template requested it; classic templates consequently
 extend ``UsingTemplateDetails`` with the same optional field.
 
 Backend order creation logic verifies every selected product:
 
 1. Resolve the template and compute the eligible product set.
 2. Ensure user selections are a subset of the resolved list and satisfy
    ``choose_one`` / quantity bounds.
 3. Construct the contract terms by embedding the selected products as line items
    in ``TemplateContractDetails`` before calling the internal order creation
    path (same code as ``POST /private/orders``).
 4. Record the chosen products in order metadata for fulfilment and reporting.
 
 When ``tip`` is present, it is simply appended as its own line item(product)
 in the order.
 
 Wallet UX
 ---------
 
 Wallets handle inventory templates as follows:
 
 1. Fetch ``WalletTemplateDetails`` and cache the resolved inventory.
 2. Render a cart builder respecting ``choose_one``.
 3. Show a running total computed from per-product prices; totals must match the
    backend response before displaying the payment acceptance dialog.
 4. Gracefully handle outdated caches by retrying the ``GET`` when the ``POST``
    returns a conflict due to inventory changes.
 
 Compatibility rules
 -------------------
 
 * Templates containing ``template_type`` = ``"inventory-cart"`` require
   merchant protocol v25 or later.
 * QR codes stay in the same pay-template URI parameters.
 
 Definition of Done
 ==================
 
 * [x] REST API changes and schema extensions are ratified by wallet and merchant.
 * [ ] Merchant SPA support for creating inventory-cart templates.
 * [ ] Integration tests cover single-product and multi-product cart creation via
   the new template type across merchant and wallet.
 * [x] Updated reference documentation describes the new template type and
   associated fields.
 * [ ] Wallet and merchant SPA have complete workflows and designs for the new
   template.
 
 
 Alternatives
 ============
 
 * Keep templates fixed and push cart building to merchant-hosted Web flows,
   trading offline capability for implementation simplicity.
 * Require merchants to mint one template per product, keeping the current API
   untouched but exacerbating QR code sprawl and inventory maintenance.
 
 Drawbacks
 =========
 
 * Larger template payloads may increase wallet fetch
   times, especially for templates with many products.
 * More complex validation paths in both wallet and merchant codebases.
 * Risk of inconsistent order totals.
 
 Discussion / Q&A
 ================
 
 What should happen when a customer wants to leave a tip?
   In the existing template version ``tip`` is supported when the merchant
   allows amount modifications. For the new ``inventory-cart`` type the
   ``request_tip`` flag makes that intent explicit. The backend simply appends
   the tip as another product that flows to the same payto target as the base
   order. Future work can revisit tip splitting, but that extra complexity is
   explicitly out of scope here.