# Inventory

Stock availability and retail store inventory

## Query retail store stock for a product

> Returns stock availability information across retail stores for a specific product.\
> \
> \*\*Purpose:\*\*\
> Enables "Click & Collect" functionality by showing which physical stores have a product in stock.\
> \
> \*\*Response:\*\*\
> Returns a list of retail stores with stock information, including:\
> \* Store location details (address, city, township)\
> \* Available stock quantity\
> \* Store contact information\
> \
> \*\*Filtering:\*\*\
> Use query parameters to narrow results by geographic area:\
> \* \`city\_id\`: Show stores in a specific city\
> \* \`township\_id\`: Show stores in a specific township\
> \* \`district\_id\`: Show stores in a specific district\
> \
> \*\*Rate Limiting:\*\*\
> This endpoint is rate-limited to prevent abuse. Excessive requests may be throttled.

```json
{"openapi":"3.1.0","info":{"title":"Product API - Product Catalog & Detail Information","version":"1.0.0"},"tags":[{"name":"Inventory","description":"Stock availability and retail store inventory"}],"servers":[{"description":"Commerce API Server","url":"https://{commerce_url}","variables":{"commerce_url":{"default":"sandbox.akinon.com","description":"Commerce server URL (e.g., your-store.akinon.com)"}}}],"paths":{"/retail_store_stock/{product_id}/":{"get":{"tags":["Inventory"],"operationId":"getRetailStoreStock","summary":"Query retail store stock for a product","description":"Returns stock availability information across retail stores for a specific product.\n\n**Purpose:**\nEnables \"Click & Collect\" functionality by showing which physical stores have a product in stock.\n\n**Response:**\nReturns a list of retail stores with stock information, including:\n* Store location details (address, city, township)\n* Available stock quantity\n* Store contact information\n\n**Filtering:**\nUse query parameters to narrow results by geographic area:\n* `city_id`: Show stores in a specific city\n* `township_id`: Show stores in a specific township\n* `district_id`: Show stores in a specific district\n\n**Rate Limiting:**\nThis endpoint is rate-limited to prevent abuse. Excessive requests may be throttled.","parameters":[{"name":"product_id","in":"path","required":true,"description":"Unique identifier of the product to check stock for.","schema":{"type":"integer"}},{"name":"city_id","in":"query","required":false,"description":"Filter stores by city.","schema":{"type":"integer"}},{"name":"township_id","in":"query","required":false,"description":"Filter stores by township (ilçe).","schema":{"type":"integer"}},{"name":"district_id","in":"query","required":false,"description":"Filter stores by district (mahalle).","schema":{"type":"integer"}}],"responses":{"200":{"description":"Store stock information retrieved successfully","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/RetailStoreStock"}}}}},"404":{"description":"Product not found"},"429":{"description":"Rate limit exceeded"}}}}},"components":{"schemas":{"RetailStoreStock":{"type":"object","description":"Retail store with stock availability information.","properties":{"pk":{"type":"integer","description":"Store identifier"},"name":{"type":"string","description":"Store name"},"erp_code":{"type":"string","description":"Store code in the ERP system.\n\nUsed for inventory synchronization."},"phone_number":{"type":"string","description":"Store contact phone number"},"address":{"type":"string","description":"Full street address"},"township":{"$ref":"#/components/schemas/Township"},"latitude":{"type":"number","format":"float","description":"Geographic latitude coordinate"},"longitude":{"type":"number","format":"float","description":"Geographic longitude coordinate"},"stock":{"type":"integer","description":"Available stock quantity at this store."},"is_available":{"type":"boolean","description":"Indicates if the product is available for collection at this store."}}},"Township":{"type":"object","description":"Township (ilçe) geographic information.","properties":{"pk":{"type":"integer","description":"Township identifier"},"name":{"type":"string","description":"Township name"},"city":{"$ref":"#/components/schemas/City"}}},"City":{"type":"object","description":"City geographic information.","properties":{"pk":{"type":"integer","description":"City identifier"},"name":{"type":"string","description":"City name"},"country":{"$ref":"#/components/schemas/Country"}}},"Country":{"type":"object","description":"Country information.","properties":{"pk":{"type":"integer","description":"Country identifier"},"name":{"type":"string","description":"Country name"},"code":{"type":"string","description":"ISO country code"}}}}}}
```

## Query stock availability for basket items

> Returns retail store stock availability for all items in the user's basket.\
> \
> \*\*Purpose:\*\*\
> Enables "Click & Collect" checkout by finding stores that have all basket items in stock.\
> \
> \*\*Authentication:\*\*\
> Requires either:\
> \* Authenticated session (logged-in user)\
> \* Valid email identifier\
> \
> \*\*Response:\*\*\
> Returns stores that can fulfill the entire basket, including:\
> \* Store details with location information\
> \* Per-product availability status\
> \* Collection tag/identifier\
> \
> \*\*Filtering:\*\*\
> Same geographic filters as single-product stock query:\
> \* \`city\_id\`, \`township\_id\`, \`district\_id\`

```json
{"openapi":"3.1.0","info":{"title":"Product API - Product Catalog & Detail Information","version":"1.0.0"},"tags":[{"name":"Inventory","description":"Stock availability and retail store inventory"}],"servers":[{"description":"Commerce API Server","url":"https://{commerce_url}","variables":{"commerce_url":{"default":"sandbox.akinon.com","description":"Commerce server URL (e.g., your-store.akinon.com)"}}}],"paths":{"/query-basket-stock/":{"get":{"tags":["Inventory"],"operationId":"queryBasketStock","summary":"Query stock availability for basket items","description":"Returns retail store stock availability for all items in the user's basket.\n\n**Purpose:**\nEnables \"Click & Collect\" checkout by finding stores that have all basket items in stock.\n\n**Authentication:**\nRequires either:\n* Authenticated session (logged-in user)\n* Valid email identifier\n\n**Response:**\nReturns stores that can fulfill the entire basket, including:\n* Store details with location information\n* Per-product availability status\n* Collection tag/identifier\n\n**Filtering:**\nSame geographic filters as single-product stock query:\n* `city_id`, `township_id`, `district_id`","parameters":[{"name":"city_id","in":"query","required":false,"description":"Filter stores by city.","schema":{"type":"integer"}},{"name":"township_id","in":"query","required":false,"description":"Filter stores by township (ilçe).","schema":{"type":"integer"}},{"name":"district_id","in":"query","required":false,"description":"Filter stores by district (mahalle).","schema":{"type":"integer"}}],"responses":{"200":{"description":"Basket stock availability retrieved successfully","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/BasketStockResult"}}}}},"401":{"description":"Authentication required.\n\nUser must be logged in or provide valid email identification."},"429":{"description":"Rate limit exceeded"}}}}},"components":{"schemas":{"BasketStockResult":{"type":"object","description":"Store availability result for basket items.","properties":{"tag":{"type":"string","description":"Collection identifier or tag for this fulfillment option."},"products":{"type":"array","description":"Products available at this store with quantities.","items":{"type":"object","properties":{"product_id":{"type":"integer","description":"Product identifier"},"quantity":{"type":"integer","description":"Available quantity"}}}},"retail_store":{"$ref":"#/components/schemas/RetailStoreStock"}}},"RetailStoreStock":{"type":"object","description":"Retail store with stock availability information.","properties":{"pk":{"type":"integer","description":"Store identifier"},"name":{"type":"string","description":"Store name"},"erp_code":{"type":"string","description":"Store code in the ERP system.\n\nUsed for inventory synchronization."},"phone_number":{"type":"string","description":"Store contact phone number"},"address":{"type":"string","description":"Full street address"},"township":{"$ref":"#/components/schemas/Township"},"latitude":{"type":"number","format":"float","description":"Geographic latitude coordinate"},"longitude":{"type":"number","format":"float","description":"Geographic longitude coordinate"},"stock":{"type":"integer","description":"Available stock quantity at this store."},"is_available":{"type":"boolean","description":"Indicates if the product is available for collection at this store."}}},"Township":{"type":"object","description":"Township (ilçe) geographic information.","properties":{"pk":{"type":"integer","description":"Township identifier"},"name":{"type":"string","description":"Township name"},"city":{"$ref":"#/components/schemas/City"}}},"City":{"type":"object","description":"City geographic information.","properties":{"pk":{"type":"integer","description":"City identifier"},"name":{"type":"string","description":"City name"},"country":{"$ref":"#/components/schemas/Country"}}},"Country":{"type":"object","description":"Country information.","properties":{"pk":{"type":"integer","description":"Country identifier"},"name":{"type":"string","description":"Country name"},"code":{"type":"string","description":"ISO country code"}}}}}}
```