commit 956d9f4114952cdc5708737fcf50046ea2c02e77
parent 8930e91a5e7cf2b75b474ae3644ab9894243d9ba
Author: Christian Grothoff <christian@grothoff.org>
Date: Tue, 30 Dec 2025 20:58:07 +0100
API cleanups, clarifications
Diffstat:
| M | core/api-merchant.rst | | | 88 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++------------------------ |
1 file changed, 62 insertions(+), 26 deletions(-)
diff --git a/core/api-merchant.rst b/core/api-merchant.rst
@@ -2863,13 +2863,13 @@ Managing product categories
**Response:**
:http:statuscode:`200 Ok`:
- The body is a `CategoryProductList`.
+ The body is a `CategoryProductListResponse`.
**Details:**
- .. ts:def:: CategoryProductList
+ .. ts:def:: CategoryProductListResponse
- interface CategoryProductList {
+ interface CategoryProductListResponse {
// Name of the category.
name: string;
@@ -2975,7 +2975,7 @@ Adding products to the inventory
**Request:**
- The request must be a `ProductAddDetail`.
+ The request must be a `ProductAddDetailRequest`.
**Response:**
@@ -2997,9 +2997,9 @@ Adding products to the inventory
**Details:**
- .. ts:def:: ProductAddDetail
+ .. ts:def:: ProductAddDetailRequest
- interface ProductAddDetail {
+ interface ProductAddDetailRequest {
// Product ID to use.
product_id: string;
@@ -3047,9 +3047,13 @@ Adding products to the inventory
total_stock?: Integer;
// Preferred way to express the per-unit price of the product. Supply at least one entry;
- // the first entry represents the base price and MUST include applicable taxes.
+ // the first entry must match ``price``.
+ // The price given MUST include applicable taxes if ``price_is_net``
+ // is false, and MUST exclude applicable taxes if ``price_is_net``
+ // is true.
// Zero implies that the product is not sold separately or that the price must be supplied
// by the frontend.
+ // Since API version **v28**.
unit_price?: Amount[];
// True if the price(s) given are a net prices, false if they are
@@ -3057,7 +3061,9 @@ Adding products to the inventory
// Since protocol **vTAXES**.
price_is_net?: boolean;
- // Legacy price field. Deprecated; when present it must match the first element of ``unit_price``.
+ // Legacy price field.
+ // Deprecated since **v28**;
+ // when present it must match the first element of ``unit_price``.
price?: Amount;
// An optional base64-encoded product image.
@@ -3134,7 +3140,7 @@ Adding products to the inventory
**Request:**
- The request must be a `ProductPatchDetail`.
+ The request must be a `ProductPatchDetailRequest`.
**Response:**
@@ -3154,9 +3160,9 @@ Adding products to the inventory
the inventory.
- .. ts:def:: ProductPatchDetail
+ .. ts:def:: ProductPatchDetailRequest
- interface ProductPatchDetail {
+ interface ProductPatchDetailRequest {
// Human-readable product name.
// Since API version **v20**. Optional only for
@@ -3195,9 +3201,12 @@ Adding products to the inventory
// the first entry represents the base price and MUST include applicable taxes.
// Zero implies that the product is not sold separately or that the price must be supplied
// by the frontend.
+ // Since API version **v28**.
unit_price?: Amount[];
- // Legacy price field. Deprecated; when present it must match the first element of ``unit_price``.
+ // Legacy price field.
+ // Deprecated since **v28**;
+ // when present it must match the first element of ``unit_price``.
price?: Amount;
// True if the price(s) given are a net prices, false if they are
@@ -3305,15 +3314,15 @@ Inspecting inventory
:http:statuscode:`200 OK`:
The backend has successfully returned the inventory. Returns
- a `ProductDetail`.
+ a `ProductDetailResponse`.
:http:statuscode:`404 Not found`:
The product (ID) is unknown to the backend.
**Details:**
- .. ts:def:: ProductDetail
+ .. ts:def:: ProductDetailResponse
- interface ProductDetail {
+ interface ProductDetailResponse {
// Human-readable product name.
// Since API version **v20**.
@@ -3348,7 +3357,9 @@ Inspecting inventory
// fixed, and must be supplied by the front-end.
unit_price: Amount[];
- // Legacy price field kept for compatibility. Deprecated; equal to the first element of ``unit_price``.
+ // Legacy price field kept for compatibility.
+ // Deprecated since **v28**;
+ // equal to the first element of ``unit_price``.
price: Amount;
// An optional base64-encoded product image.
@@ -3992,7 +4003,7 @@ Creating orders
minimum_age?: Integer;
// List of products that are part of the purchase.
- products?: Product[];
+ products?: ProductSold[];
// Time when this contract was generated. If null, defaults to current
// time of merchant backend.
@@ -4042,7 +4053,7 @@ Creating orders
extra?: Object;
// Money pot to increment for whatever order payment amount
- // is not yet assigned to a pot via the ``Product``.
+ // is not yet assigned to a pot via the ``ProductSold``.
// Not useful to wallets, only for
// merchant-internal accounting.
// Since protocol **vPOTS**.
@@ -4166,11 +4177,13 @@ Creating orders
// Which product is requested (here mandatory!).
product_id: string;
- // Legacy integer quantity. Deprecated; defaults to 1 if both
- // ``quantity`` and ``unit_quantity`` are absent.
+ // Legacy integer quantity.
+ // Deprecated since **v28**;
+ // defaults to 1 if both ``quantity`` and ``unit_quantity`` are absent.
quantity?: Integer;
// Preferred quantity string using "<integer>[.<fraction>]" syntax.
+ // @since **v28**;
unit_quantity?: string
// Money pot to use for this product, overrides value from
@@ -6766,8 +6779,8 @@ The contract terms must have the following structure:
// messages.
fulfillment_message_i18n?: { [lang_tag: string]: string };
- // List of products that are part of the purchase (see `Product`).
- products: Product[];
+ // List of products that are part of the purchase (see `ProductSold`).
+ products: ProductSold[];
// Time when this contract was generated.
timestamp: Timestamp;
@@ -7048,12 +7061,14 @@ The wallet must select an exchange that either the merchant accepts directly by
listing it in the exchanges array, or for which the merchant accepts an auditor
that audits that exchange by listing it in the auditors array.
-The `Product` object describes the product being purchased from the merchant.
+The `ProductSold` object describes a product and the quantity
+being purchased from the merchant as well as possibly the price
+and applicable taxes.
It has the following structure:
-.. ts:def:: Product
+.. ts:def:: ProductSold
- interface Product {
+ interface ProductSold {
// Merchant-internal identifier for the product.
product_id?: string;
@@ -7079,13 +7094,34 @@ It has the following structure:
// Unit in which the product is measured (liters, kilograms, packages, etc.).
unit?: string;
- // The price of the product; this is the total price for ``quantity`` times ``unit`` of this product.
+ // The price of the product;
+ // Deprecated since **v28**;
+ // this is the total price
+ // for ``quantity`` times ``unit`` of this product.
price?: Amount;
+ // Price of ``unit_quantity`` units of the product in various currencies.
+ // Zero or absent implies that the product is not sold
+ // separately.
+ // Since API version **v28**.
+ prices?: Amount[];
+
+ // True if the ``prices`` given are the net price,
+ // false if they are the gross price. Note that even ``prices`` are the
+ // gross price, ``taxes`` may be missing if the merchant configured
+ // gross ``prices`` but did not configure any ``taxes``.
+ // Similarly, the merchant may have configured net ``prices``
+ // for products but deals with taxes on a per-order basis. Thus, it
+ // may not always be possible to compute the gross price from the net
+ // price for an individual product, necessitating this flag.
+ // Since protocol **vTAXES**.
+ prices_are_net: boolean;
+
// An optional base64-encoded product image.
image?: ImageDataUrl;
// A list of taxes paid by the merchant for this product. Can be empty.
+ // Will likely change soon!
taxes?: Tax[];
// Time indicating when this product should be delivered.
