POST [/instances/$INSTANCE]/private/products/$PRODUCT_ID/lock

This is used to lock a certain quantity of the product for a limited duration while the customer assembles a complete order. Note that frontends do not have to “unlock”, they may rely on the timeout as given in the duration field. Re-posting a lock with a different duration or quantity updates the existing lock for the same UUID and does not result in a conflict.

Unlocking by using a quantity of zero is optional but recommended if customers remove products from the shopping cart. Note that actually POSTing to /orders with set inventory_products and using lock_uuids will transition the lock to the newly created order (which may have a different duration and quantity than what was requested in the lock operation). If an order is for fewer items than originally locked, the difference is automatically unlocked.

Required permission: products-lock

Request:

The request must be a LockRequest.

Response:

204 No content:

The backend has successfully locked (or unlocked) the requested quantity.

404 Not found:

The backend has does not know this product.

410 Gone:

The backend does not have enough of product in stock. Returns an OutOfStockResponse.

Details:

interface LockRequest {

  // UUID that identifies the frontend performing the lock
  // Must be unique for the lifetime of the lock.
  lock_uuid: string;

  // How long does the frontend intend to hold the lock?
  duration: RelativeTime;

  // Legacy integer quantity to lock. Deprecated; defaults to 1 if both
  // quantity and unit_quantity are absent.
  quantity?: Integer;

  // Preferred way to express the requested quantity using "<integer>[.<fraction>]" syntax.
  unit_quantity?: string;

}

At least one of quantity or unit_quantity must be supplied; omitting both defaults to a quantity of one. unit_quantity follows the same decimal-string format described for unit_total_stock.

Note

The GNUNET_CRYPTO_random_timeflake() C API can be used to generate such timeflakes for clients written in C.