--- title: Stocks slug: merchant-api/stocks createdAt: 2021-10-07T15:02:11.000Z --- # Definition Stock corresponds to the actual `quantity` available for a given SKU. It can include several warehouse stock values as well, if applicable. :::hint{type="info"} - Stock should always be sent as the **absolute** **value** at a given time, which corresponds to the total quantity available. - Stock not sent to Neteven remains unchanged in the Neteven User Interface, *unless *there is another stock entry point used (manual change in the UI, file import, etc). - Stock visible on Marketplace depends on publication rule configuration done within the Neteven user interface: a quantity sent via the API is not necessarily the one visible on the Marketplace site. - Neteven has an internal stock management mechanism to decrement available stock pushed to multiple Marketplaces based on pending orders. You should know this and take it into account when designing your stock update connection to Neteven. ::: # Endpoints ## Update stock ### Endpoint definition | `PATCH` | `/merchant/items/stocks` | | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Description** | Update item `quantity` and `warehouse.stock` on a range of items. | | **Required scope** | `stock_manager` | | **Request payload** | You can send up to 1000 items in the same request. If you have more items to update during a stock update iteration, make sure to batch your updates in subsequent requests. | | **Returns** | **- **If the entire payload is successfully processed, the API will not return a body.
**-** If the payload contains errors, they will be displayed per item in the response body. | :::hint{type="success"} **Stock updates rules of thumb: ** - You cannot create new SKU's with this endpoint. Stock updates only work on already existing SKU's. - Only send stock updates on products which changed since last iteration: avoid sending unnecessary items. - Parse the body of the response: errors are included and should be fixed before re-submitting. - Trust the API response: if it says "OK", then you don't need to retrieve stock to check if it matches what you sent. ::: **example:** :::CodeblockTabs stock update ```curl curl --request PATCH \ --url https://api.neteven.com/v1/merchant/items/stocks \ --header 'Accept: application/json' \ --header 'Authorization: Bearer $MYTOKEN' \ --header 'Content-Type: application/json' \ --data '{ "items": [ { "quantity": 10, "sku": "68471-NPO-GFM_123456" }, { "items": [ { "quantity": 0, "sku": "7613214699873", "warehouses": [ { "id": 1044, "sku": "7613214699873", "stock": 10 } ] }, { "quantity": 10, "sku": "68092-AAG-GFM" } ] }' ``` 207 Multi Status response ```javascript { "data": { "items": [ { "sku": "68471-NPO-GFM_123456", "status": { "message": "Sku 68471-NPO-GFM_123456 does not exist", "code": 404, "title": "Not Found" } }, { "sku": "69023-AAM-GHTP", "status": { "message": "Updated", "code": 200, "title": "Ok" } }, { "sku": "68092-AAG-GFM", "status": { "message": "Updated", "code": 200, "title": "Ok" } } ] }, "metadata": { "api_version": 1, "api_version_expiration_date": "2022-12-31", "number_of_results": 3 } } ``` ::: ### Endpoint specific errors **Response HTTP Header code :** `400` **Cause:** Duplicated SKU in request body :::BlockQuote The SKU '{sku}' is listed more than once in your payload. Please remove duplicates before resubmitting. ::: **Actionable :** Ensure every SKU is only included once per payload. *** **Response HTTP Header code :** `207` **Cause:** Partial error management possible. If at least one of the SKU's submitted is not recognized, the request will return a HTTP 207 code, while listing the items which could not be processed in the response body: - item code **404**: the SKU submitted does not exist on your account. **Actionable :** Fix the item select logic on your side to only include those already created in Neteven. :::hint{type="warning"} This error is most likely due to a erroneous integration: do NOT push SKU's which do not yet exist on your Neteven account. Create them first before trying to update their prices. ::: **Sub status messages (**`data.items[].status`**):** :::BlockQuote \{ "message": "Sku {sku} does not exist", "code": 404, "title": "Not Found } ::: *** ## Retrieve item stock ### Endpoint definition | `GET` | `/merchant/items/stocks` | | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Description** | Returns the stock values per SKU, as it is registered within the Neteven system.
| | **Required scope** | `stock_reader` | | **Pagination** | Please note that by default a maximum of
1000 items will be displayed in a response. Please use parameters to
get results customized to your requirements. | | **Filtering** | use filtering to scope specific SKU's or EAN codes when calling. | | **Returns** | array of `item` objects, including their quantity and warehouse.stocks if any. | **** **Example:** :::CodeblockTabs Get stocks ```curl curl --request GET \ --url https://api.neteven.com/v1/merchant/items/stocks?limit=5 \ --header 'Accept: application/json' \ --header 'Authorization: Bearer $MYTOKEN' \ --header 'Content-Type: application/json' ``` 200 OK Response ```javascript { "data": { "items": [ { "quantity": 10, "quantity_reserved": 1, "quanity_availabe": 9, "sku": "68471-NPO-GFM" }, { "quantity": 10, "sku": "69023-AAM-GHTP", "warehouses": [ { "stock": 20, "sku": "", "name": "Warehouse1", "id": 513 } ] }, { "quantity": 10, "quantity_reserved": 3, "quanity_availabe": 7, "sku": "68092-AAG-GFM" }, { "quantity": 10, "quantity_reserved": 10, "quanity_availabe": 0, "sku": "KPWJK053.-.NVY.L" }, { "quantity": 10, "quantity_reserved": 0, "quanity_availabe": 10, "sku": "KPWJK053.-.NVY.XL" } ] }, "metadata": { "number_of_results": 5, "api_version": 1, "api_version_expiration_date": "2022-12-31", "total_count": 188008, "limit": 5, "offset": 0 } } ``` ::: ### Endpoint specific errors :::hint{type="success"} There is no error returned by this view (it will always return a `HTTP 200` status code). If no item in our system match the submitted query parameter filtering criteria, the response body will simply be an empty list. ::: *** # API reference *more information on parameters, responses and content in the *[API Reference](docId\:yWeBKEf7Kqp3agiK6LtoJ)