patch-private-products-PRODUCT_ID.rst (5637B)
1 .. http:patch:: [/instances/$INSTANCE]/private/products/$PRODUCT_ID 2 3 This is used to update product details in the inventory. Note that the 4 ``total_stock`` and ``total_lost`` numbers MUST be greater or equal than 5 previous values (this design ensures idempotency). In case stocks were lost 6 but not sold, increment the ``total_lost`` number. All fields in the 7 request are optional, those that are not given are simply preserved (not 8 modified). Note that the ``description_i18n`` and ``taxes`` can only be 9 modified in bulk: if it is given, all translations must be provided, not 10 only those that changed. ``never`` should be used for the ``next_restock`` 11 timestamp to indicate no intention/possibility of restocking, while a time 12 of zero is used to indicate "unknown". 13 14 **Required permission:** ``products-write`` 15 16 **Request:** 17 18 The request must be a `ProductPatchDetailRequest`. 19 20 **Response:** 21 22 :http:statuscode:`204 No content`: 23 The backend has successfully expanded the inventory. 24 :http:statuscode:`400 Bad Request`: 25 The request body is malformed or a validation check failed. 26 Returned with ``TALER_EC_GENERIC_PARAMETER_MALFORMED`` or 27 ``TALER_EC_MERCHANT_PRIVATE_PATCH_PRODUCTS_TOTAL_LOST_EXCEEDS_STOCKS``. 28 :http:statuscode:`404 Not found`: 29 The instance, product, category, product group or money pot specified are 30 unknown. Possible error ``code`` values are thus: 31 ``TALER_EC_MERCHANT_GENERIC_INSTANCE_UNKNOWN`` (instance unknown), 32 ``TALER_EC_MERCHANT_GENERIC_PRODUCT_UNKNOWN`` (product unknown), 33 ``TALER_EC_MERCHANT_GENERIC_PRODUCT_GROUP_UNKNOWN`` (product group unknown) 34 ``TALER_EC_MERCHANT_GENERIC_MONEY_POT_UNKNOWN`` (money pot unknown), 35 ``TALER_EC_MERCHANT_GENERIC_CATEGORY_UNKNOWN`` 36 (category unknown, specific category is given in the details). 37 :http:statuscode:`409 Conflict`: 38 The provided information is inconsistent with the current state of 39 the inventory. 40 Returned with ``TALER_EC_MERCHANT_PRIVATE_PATCH_PRODUCTS_TOTAL_LOST_REDUCED``, 41 ``TALER_EC_MERCHANT_PRIVATE_PATCH_PRODUCTS_TOTAL_SOLD_REDUCED``, or 42 ``TALER_EC_MERCHANT_PRIVATE_PATCH_PRODUCTS_TOTAL_STOCKED_REDUCED``. 43 :http:statuscode:`500 Internal Server Error`: 44 The server experienced an internal failure. 45 Returned with ``TALER_EC_GENERIC_DB_STORE_FAILED``, 46 ``TALER_EC_GENERIC_DB_FETCH_FAILED`` or 47 ``TALER_EC_GENERIC_INTERNAL_INVARIANT_FAILURE``. 48 49 .. ts:def:: ProductPatchDetailRequest 50 51 interface ProductPatchDetailRequest { 52 53 // Human-readable product name. 54 // Since API version **v20**. Optional only for 55 // backwards-compatibility, should be considered mandatory 56 // moving forward! 57 product_name?: string; 58 59 // Human-readable product description. 60 description: string; 61 62 // Map from IETF BCP 47 language tags to localized descriptions. 63 description_i18n?: { [lang_tag: string]: string }; 64 65 // Unit in which the product is measured (liters, kilograms, packages, etc.). 66 unit: string; 67 68 // Optional override to control whether fractional quantities are permitted. 69 unit_allow_fraction?: boolean; 70 71 // Override for the fractional precision level (0-6). Only relevant if 72 // ``unit_allow_fraction`` is true. 73 unit_precision_level?: Integer; 74 75 // Categories into which the product belongs. 76 // Used in the POS-endpoint. 77 // Since API version **v16**. 78 categories?: Integer[]; 79 80 // Preferred way to express the per-unit price. Supply at least one entry; 81 // the first entry represents the base price and MUST include applicable taxes. 82 // Zero implies that the product is not sold separately or that the price must be supplied 83 // by the frontend. 84 // Each entry must use a distinct currency. 85 // Since API version **v25**. 86 // Currency uniqueness enforced since protocol **v25**. 87 unit_price?: Amount[]; 88 89 // Legacy price field. 90 // Deprecated since **v25**; 91 // when present it must match the first element of ``unit_price``. 92 price?: Amount; 93 94 // True if the price(s) given are a net prices, false if they are 95 // gross prices. 96 // Since protocol **vTAXES**. 97 price_is_net?: boolean; 98 99 // An optional base64-encoded product image. 100 image?: ImageDataUrl; 101 102 // A list of taxes paid by the merchant for one unit of this product. 103 taxes?: Tax[]; 104 105 // Preferred way to express inventory counts using "<integer>[.<fraction>]" syntax. 106 // Use "-1" for unlimited stock. 107 unit_total_stock?: DecimalQuantity; 108 109 // Legacy stock counter. Deprecated, use ``unit_total_stock`` instead. 110 total_stock?: Integer; 111 112 // Number of units of the product that were lost (spoiled, stolen, etc.). 113 total_lost?: Integer; 114 115 // Identifies where the product is in stock. 116 address?: Location; 117 118 // Identifies when we expect the next restocking to happen. 119 next_restock?: Timestamp; 120 121 // Minimum age buyer must have (in years). Default is 0. 122 minimum_age?: Integer; 123 124 // Product group the product belongs to. 0 and missing both 125 // means default. 126 // Since **v25**. 127 product_group_id?: Integer; 128 129 // Money pot revenue on the product should be accounted in. 130 // 0 and missing both mean no money pot (revenue accounted 131 // in money pot of the overall order or not at all). 132 // Since **v25**. 133 money_pot_id?: Integer; 134 135 } 136 137 The same compatibility rules for the ``unit_*`` fields and their deprecated counterparts apply 138 when patching an existing product.