post-private-products-PRODUCT_ID-lock.rst (2356B)
1 .. http:post:: [/instances/$INSTANCE]/private/products/$PRODUCT_ID/lock 2 3 This is used to lock a certain quantity of the product for a limited 4 duration while the customer assembles a complete order. Note that 5 frontends do not have to "unlock", they may rely on the timeout as 6 given in the ``duration`` field. Re-posting a lock with a different 7 ``duration`` or ``quantity`` updates the existing lock for the same UUID 8 and does not result in a conflict. 9 10 Unlocking by using a ``quantity`` of zero is 11 optional but recommended if customers remove products from the 12 shopping cart. Note that actually POSTing to ``/orders`` with set 13 ``inventory_products`` and using ``lock_uuids`` will **transition** the 14 lock to the newly created order (which may have a different ``duration`` 15 and ``quantity`` than what was requested in the lock operation). 16 If an order is for fewer items than originally locked, the difference 17 is automatically unlocked. 18 19 **Required permission:** ``products-lock`` 20 21 **Request:** 22 23 The request must be a `LockRequest`. 24 25 **Response:** 26 27 :http:statuscode:`204 No content`: 28 The backend has successfully locked (or unlocked) the requested ``quantity``. 29 :http:statuscode:`404 Not found`: 30 The backend has does not know this product. 31 :http:statuscode:`410 Gone`: 32 The backend does not have enough of product in stock. Returns an `OutOfStockResponse`. 33 34 **Details:** 35 36 .. ts:def:: LockRequest 37 38 interface LockRequest { 39 40 // UUID that identifies the frontend performing the lock 41 // Must be unique for the lifetime of the lock. 42 lock_uuid: string; 43 44 // How long does the frontend intend to hold the lock? 45 duration: RelativeTime; 46 47 // Legacy integer quantity to lock. Deprecated; defaults to 1 if both 48 // ``quantity`` and ``unit_quantity`` are absent. 49 quantity?: Integer; 50 51 // Preferred way to express the requested quantity using "<integer>[.<fraction>]" syntax. 52 unit_quantity?: string; 53 54 } 55 56 At least one of ``quantity`` or ``unit_quantity`` must be supplied; omitting both defaults to a 57 quantity of one. ``unit_quantity`` follows the same decimal-string format described for 58 ``unit_total_stock``. 59 60 .. note:: 61 62 The ``GNUNET_CRYPTO_random_timeflake()`` C API can be used 63 to generate such timeflakes for clients written in C.