taler-docs

patch-private-products-PRODUCT_ID.rst (5402B)

---

 .. http:patch:: [/instances/$INSTANCE]/private/products/$PRODUCT_ID
 
   This is used to update product details in the inventory. Note that the
   ``total_stock`` and ``total_lost`` numbers MUST be greater or equal than
   previous values (this design ensures idempotency).  In case stocks were lost
   but not sold, increment the ``total_lost`` number.  All fields in the
   request are optional, those that are not given are simply preserved (not
   modified).  Note that the ``description_i18n`` and ``taxes`` can only be
   modified in bulk: if it is given, all translations must be provided, not
   only those that changed.  ``never`` should be used for the ``next_restock``
   timestamp to indicate no intention/possibility of restocking, while a time
   of zero is used to indicate "unknown".
 
   **Required permission:** ``products-write``
 
   **Request:**
 
   The request must be a `ProductPatchDetailRequest`.
 
   **Response:**
 
   :http:statuscode:`204 No content`:
     The backend has successfully expanded the inventory.
   :http:statuscode:`400 Bad Request`:
     The request body is malformed or a validation check failed.
   :http:statuscode:`404 Not found`:
     The instance, product, category, product group or money pot specified are
     unknown. Possible error ``code`` values are thus:
     ``TALER_EC_MERCHANT_GENERIC_INSTANCE_UNKNOWN`` (instance unknown),
     ``TALER_EC_MERCHANT_GENERIC_PRODUCT_UNKNOWN`` (product unknown),
     ``TALER_EC_MERCHANT_GENERIC_PRODUCT_GROUP_UNKNOWN`` (product group unknown)
     ``TALER_EC_MERCHANT_GENERIC_MONEY_POT_UNKNOWN`` (money pot unknown),
     ``TALER_EC_MERCHANT_GENERIC_CATEGORY_UNKNOWN``
     (category unknown, specific category is given in the details).
   :http:statuscode:`409 Conflict`:
     The provided information is inconsistent with the current state of
     the inventory.
     Returned with ``TALER_EC_MERCHANT_PRIVATE_PATCH_PRODUCTS_TOTAL_LOST_REDUCED``,
     ``TALER_EC_MERCHANT_PRIVATE_PATCH_PRODUCTS_TOTAL_SOLD_REDUCED``, or
     ``TALER_EC_MERCHANT_PRIVATE_PATCH_PRODUCTS_TOTAL_STOCKED_REDUCED``.
   :http:statuscode:`500 Internal Server Error`:
     The server experienced an internal failure.
     Returned with ``TALER_EC_GENERIC_DB_STORE_FAILED``.
 
   .. ts:def:: ProductPatchDetailRequest
 
     interface ProductPatchDetailRequest {
 
       // Human-readable product name.
       // Since API version **v20**.  Optional only for
       // backwards-compatibility, should be considered mandatory
       // moving forward!
       product_name?: string;
 
       // Human-readable product description.
       description: string;
 
       // Map from IETF BCP 47 language tags to localized descriptions.
       description_i18n?: { [lang_tag: string]: string };
 
       // Unit in which the product is measured (liters, kilograms, packages, etc.).
       unit: string;
 
       // Optional override to control whether fractional quantities are permitted.
       unit_allow_fraction?: boolean;
 
       // Override for the fractional precision level (0-6). Only relevant if
       // ``unit_allow_fraction`` is true.
       unit_precision_level?: Integer;
 
       // Categories into which the product belongs.
       // Used in the POS-endpoint.
       // Since API version **v16**.
       categories?: Integer[];
 
       // Preferred way to express the per-unit price. Supply at least one entry;
       // 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.
       // Each entry must use a distinct currency.
       // Since API version **v25**.
       // Currency uniqueness enforced since protocol **v25**.
       unit_price?: Amount[];
 
       // Legacy price field.
       // Deprecated since **v25**;
       // 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
       // gross prices.
       // Since protocol **vTAXES**.
       price_is_net?: boolean;
 
       // An optional base64-encoded product image.
       image?: ImageDataUrl;
 
       // A list of taxes paid by the merchant for one unit of this product.
       taxes?: Tax[];
 
       // Preferred way to express inventory counts using "<integer>[.<fraction>]" syntax.
       // Use "-1" for unlimited stock.
       unit_total_stock?: DecimalQuantity;
 
       // Legacy stock counter. Deprecated, use ``unit_total_stock`` instead.
       total_stock?: Integer;
 
       // Number of units of the product that were lost (spoiled, stolen, etc.).
       total_lost?: Integer;
 
       // Identifies where the product is in stock.
       address?: Location;
 
       // Identifies when we expect the next restocking to happen.
       next_restock?: Timestamp;
 
       // Minimum age buyer must have (in years). Default is 0.
       minimum_age?: Integer;
 
       // Product group the product belongs to. 0 and missing both
       // means default.
       // Since **v25**.
       product_group_id?: Integer;
 
       // Money pot revenue on the product should be accounted in.
       // 0 and missing both mean no money pot (revenue accounted
       // in money pot of the overall order or not at all).
       // Since **v25**.
       money_pot_id?: Integer;
 
     }
 
   The same compatibility rules for the ``unit_*`` fields and their deprecated counterparts apply
   when patching an existing product.