# Product Stock

This article provides comprehensive information and documentation on a set of API methods specifically designed to handle product stocks. By leveraging these methods, users can retrieve, search, and create product stocks, allowing for seamless integration and management of product stock data within the system.

The article includes detailed explanations, parameter descriptions, and usage examples for each API method, empowering developers to effectively utilize the capabilities provided by the product stock API.

### `GET` Product Stock

Product Stock is responsible for keeping track of stock details of the related product within the specified stock list. There might be more than one piece of stock information for a product. Each product and stock list key pair is unique.

**Path:** `/api/i1/product_stock/`

* `content_type` header represents the response type.
* `Authorization` header is required for authentication. The `api_token` can be retrieved upon login.

**Example Request**

This request is used to retrieve all product stock data according to the limit and page parameters.

```python
import requests

url = "https://{customer_api_url}/api/i1/product_stock/"
api_token = "f532eXXXXXXXXXXXXXXXXX201XXXXX9332d"

headers = {
    'content-type': 'application/json',
    'Authorization': 'Token {}'.format(api_token)
}

params = {
    'limit': '4',
    'page': '1'
}

response = requests.get(url, headers=headers , params=params)
print(response.text)
```

**Example Response (200 OK)**

Response contains all stock data with given parameters. Response status is expected to be HTTP-200 Successful. Resource properties are in Python format.

| Property                   | Data Type   | Description                                                    |
| -------------------------- | ----------- | -------------------------------------------------------------- |
| id                         | integer     | ID                                                             |
| product\_sku               | string      | Product SKU                                                    |
| stock                      | integer     | Amount of Stock (min: 0, max: 2147483647)                      |
| stock\_list                | pk field    | Stock List Primary Key                                         |
| unit\_type                 | string      | Stocked Quantity Type (qty: Quantity, kg: Kilogram)            |
| sold\_quantity\_unreported | integer     | Unreported Sold Quantity (min: 0, max: 2147483647)             |
| extra\_field               | JSON object | Extra information field for related stock item of the product. |

Additional metadata:

* count: Number of product stocks in the system.
* next: URL for the next page of product stocks.
* previous: URL for the previous page of product stocks.
* results: Array containing product stock details.

```json
{
  "count": 1012,
  "next": "https://{customer_api_url}/api/i1/product_stock/?limit=4&page=2",
  "previous": null,
  "results": [
    {
      "id": 340,
      "product_sku": "1116131001",
      "stock": 100,
      "stock_list": 1,
      "unit_type": "qty",
      "sold_quantity_unreported": 25
      "extra_field": {
        "test":"test"
      }
    }
  ]
}
```

### `POST` Create or Update Stock

This API follows an upsert logic:

* If the stock list already contains the product SKU, the stock will be updated.
* If the product SKU is not in the stock list, a new stock entry is created.

To create or update a product's stock, the `stock_list` ID is required. Refer to this section for obtaining stock list details.

**Path:** `/api/i1/product_stock/`

* `content_type` header represents the response type.
* `Authorization` header is required for authentication. The `api_token` can be retrieved upon login.

**Request Parameters**

| Parameter                  | Data Type   | Default                                                                  | Required | Description                                                    |
| -------------------------- | ----------- | ------------------------------------------------------------------------ | -------- | -------------------------------------------------------------- |
| product\_sku               | string      |                                                                          | Yes      | Product SKU                                                    |
| stock                      | integer     | 0 during creation, no default in update; if not sent, update is skipped. | No       | Stock Amount (min: 0, max: 2147483647)                         |
| stock\_list                | pk field    |                                                                          | Yes      | Stock List Primary Key                                         |
| unit\_type                 | string      | qty                                                                      | No       | Stocked quantity type. (qty: Quantity, kg: Kilogram)           |
| sold\_quantity\_unreported | integer     |                                                                          | No       | Unreported Sold Quantity (min: 0, max: 2147483647)             |
| extra\_field               | JSON object |                                                                          | No       | Extra information field for related stock item of the product. |

**Example Request**

This request is used to create a new product stock according to the given body.

```python
import requests
import json

url = "https://{customer_api_url}/api/i1/product_stock/"
api_token = "f532eXXXXXXXXXXXXXXXXX201XXXXX9332d"

headers = {
    'content-type': 'application/json',
    'Authorization': 'Token {}'.format(api_token)
}

data = {
      'product_sku': '1116131001',
      'stock': 500,
      'stock_list': 2,
      'unit_type': 'qty',
      "sold_quantity_unreported": 25
      "extra_field": {
        "test":"test"
      }   
}
response = requests.post(url, headers=headers, data=json.dumps(data))
print(response.text)
```

**Example Response (201 Created)**

A successful response returns HTTP-201 and the created stock details.

```json
{
  "id": 1270,
  "product_sku": "1116131001",
  "stock": 500,
  "stock_list": 2,
  "unit_type": "qty",
  "sold_quantity_unreported": 25
  "extra_field": {
    "test":"test"
  }
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://apidocs.akinon.com/omnitron/integration/stock/product-stock.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.