taler-docs

commit 26a65d069910ab021e7a7b2fe157da289b4d6647
parent 515da9b0a007b6083e2a344b5c9fa9d643ad7bc2
Author: Christian Grothoff <christian@grothoff.org>
Date:   Thu,  4 Jun 2026 20:30:27 +0200

spec updates for #11405 and #11415

Diffstat:
M
core/api-merchant.rst
 | 
1
+
M
core/merchant/delete-private-products-PRODUCT_ID.rst
 | 
20
+++++++++++++++++---
M
core/merchant/post-private-orders.rst
 | 
4
++++

3 files changed, 22 insertions(+), 3 deletions(-)
diff --git a/core/api-merchant.rst b/core/api-merchant.rst
@@ -58,6 +58,7 @@ The currently implemented protocol version is **v30**.
 * ``v29``: adds ``max_pickup_duration`` to templates (for Paivana)
 * ``v30``: adds ``debit_restrictions`` to GET /exchanges (for SPA)
 * ``v31``: adds ``/private/accept-tos-early`` and related API changes
+* ``v32``: adds "force" argument for locked product deletion
 
 **Upcoming versions:**
 
diff --git a/core/merchant/delete-private-products-PRODUCT_ID.rst b/core/merchant/delete-private-products-PRODUCT_ID.rst
@@ -1,10 +1,23 @@
 .. http:delete:: [/instances/$INSTANCE]/private/products/$PRODUCT_ID
 
-  Delete information about a product.  Fails if the product is locked by
-  anyone.
+  Delete information about a product.  By default this fails if the product
+  is locked by anyone (for example because units are reserved by a shopping
+  cart or an unpaid order).  Deletion can be forced using the ``force``
+  query parameter, in which case any locks held on the product are released
+  before it is deleted.  Note that forcing the deletion of a locked product
+  may disrupt customer flows that depend on those locks (such as pending
+  shopping carts), so it should be used with care.
 
   **Required permission:** ``products-write``
 
+  **Request:**
+
+  :query force: *Optional.* If set to ``yes``, the product is deleted even
+    if it is currently locked, releasing any locks held on it.  Any other
+    value (or omitting the parameter) keeps the default behavior of
+    refusing to delete a locked product. 
+    Since protocol **v32**.
+
   **Response:**
 
   :http:statuscode:`204 No content`:
@@ -16,7 +29,8 @@
     The backend does not know the instance or the product.
     Returned with ``TALER_EC_MERCHANT_GENERIC_PRODUCT_UNKNOWN``.
   :http:statuscode:`409 Conflict`:
-    The backend refuses to delete the product because it is locked.
+    The backend refuses to delete the product because it is locked
+    and ``force`` was not set to ``yes``.
     Returned with ``TALER_EC_MERCHANT_PRIVATE_DELETE_PRODUCTS_CONFLICTING_LOCK``.
   :http:statuscode:`500 Internal Server Error`:
     The server experienced an internal failure.
diff --git a/core/merchant/post-private-orders.rst b/core/merchant/post-private-orders.rst
@@ -179,9 +179,13 @@
       unit_requested_quantity: string;
 
       // Legacy integer availability (must be below ``requested_quantity``).
+      // This is the quantity actually available for new orders: it excludes
+      // units already sold or lost as well as units currently reserved by
+      // locks (shopping carts and unpaid orders).
       available_quantity: Integer;
 
       // Available quantity using "<integer>[.<fraction>]" syntax with up to six fractional digits.
+      // Like ``available_quantity``, this excludes units reserved by locks.
       unit_available_quantity: string;
 
       // When do we expect the product to be again in stock?