zoho-inventory

# Zoho Inventory Access the Zoho Inventory API with managed OAuth authentication. Manage items, sales orders, invoices, purchase orders, bills, contacts, shipment orders, and item groups with full CRUD operations. ## Quick Start ```bash # List items python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/zoho-inventory/inventory/v1/items') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` ## Base URL ``` https://gateway.maton.ai/zoho-inventory/inventory/v1/{endpoint} ``` The gateway proxies requests to `www.zohoapis.com/inventory/v1` and automatically injects your OAuth token. ## Authentication All requests require the Maton API key in the Authorization header: ``` Authorization: Bearer $MATON_API_KEY ``` **Environment Variable:** Set your API key as `MATON_API_KEY`: ```bash export MATON_API_KEY="YOUR_API_KEY" ``` ### Getting Your API Key 1. Sign in or create an account at [maton.ai](https://maton.ai) 2. Go to [maton.ai/settings](https://maton.ai/settings) 3. Copy your API key ## Connection Management Manage your Zoho Inventory OAuth connections at `https://ctrl.maton.ai`. ### List Connections ```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections?app=zoho-inventory&status=ACTIVE') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` ### Create Connection ```bash python <<'EOF' import urllib.request, os, json data = json.dumps({'app': 'zoho-inventory'}).encode() req = urllib.request.Request('https://ctrl.maton.ai/connections', data=data, method='POST') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('Content-Type', 'application/json') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` ### Get Connection ```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` **Response:** ```json { "connection": { "connection_id": "21fd90f9-5935-43cd-b6c8-bde9d915ca80", "status": "ACTIVE", "creation_time": "2025-12-08T07:20:53.488460Z", "last_updated_time": "2026-01-31T20:03:32.593153Z", "url": "https://connect.maton.ai/?session_token=...", "app": "zoho-inventory", "metadata": {} } } ``` Open the returned `url` in a browser to complete OAuth authorization. ### Delete Connection ```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}', method='DELETE') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` ### Specifying Connection If you have multiple Zoho Inventory connections, specify which one to use with the `Maton-Connection` header: ```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/zoho-inventory/inventory/v1/items') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('Maton-Connection', '21fd90f9-5935-43cd-b6c8-bde9d915ca80') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` If omitted, the gateway uses the default (oldest) active connection. ## API Reference ### Available Modules | Module | Endpoint | Description | |--------|----------|-------------| | Items | `/items` | Products and services | | Item Groups | `/itemgroups` | Grouped product variants | | Contacts | `/contacts` | Customers and vendors | | Sales Orders | `/salesorders` | Sales orders | | Invoices | `/invoices` | Sales invoices | | Purchase Orders | `/purchaseorders` | Purchase orders | | Bills | `/bills` | Vendor bills | | Shipment Orders | `/shipmentorders` | Shipment tracking | ### Items #### List Items ```bash GET /zoho-inventory/inventory/v1/items ``` **Example:** ```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/zoho-inventory/inventory/v1/items') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` **Response:** ```json { "code": 0, "message": "success", "items": [ { "item_id": "1234567890000", "name": "Widget", "status": "active", "sku": "WDG-001", "rate": 25.00, "purchase_rate": 10.00, "is_taxable": true } ], "page_context": { "page": 1, "per_page": 200, "has_more_page": false } } ``` #### Get Item ```bash GET /zoho-inventory/inventory/v1/items/{item_id} ``` #### Create Item ```bash POST /zoho-inventory/inventory/v1/items Content-Type: application/json { "name": "Widget", "rate": 25.00, "purchase_rate": 10.00, "sku": "WDG-001", "item_type": "inventory", "product_type": "goods", "unit": "pcs", "is_taxable": true } ``` **Required Fields:** - `name` - Item name **Optional Fields:** - `rate` - Sales price - `purchase_rate` - Purchase cost - `sku` - Stock keeping unit (unique) - `item_type` - `inventory`, `sales`, `purchases`, or `sales_and_purchases` - `product_type` - `goods` or `service` - `unit` - Unit of measurement - `is_taxable` - Tax applicability - `tax_id` - Tax identifier - `description` - Item description - `reorder_level` - Reorder point - `vendor_id` - Preferred vendor **Example:** ```bash python <<'EOF' import urllib.request, os, json data = json.dumps({ "name": "Widget", "rate": 25.00, "purchase_rate": 10.00, "sku": "WDG-001", "item_type": "inventory", "product_type": "goods", "unit": "pcs" }).encode() req = urllib.request.Request('https://gateway.maton.ai/zoho-inventory/inventory/v1/items', data=data, method='POST') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('Content-Type', 'application/json') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` **Response:** ```json { "code": 0, "message": "The item has been added.", "item": { "item_id": "1234567890000", "name": "Widget", "status": "active", "rate": 25.00, "purchase_rate": 10.00, "sku": "WDG-001" } } ``` #### Update Item ```bash PUT /zoho-inventory/inventory/v1/items/{item_id} Content-Type: application/json { "name": "Updated Widget", "rate": 30.00 } ``` #### Delete Item ```bash DELETE /zoho-inventory/inventory/v1/items/{item_id} ``` #### Item Status Actions ```bash # Mark as active POST /zoho-inventory/inventory/v1/items/{item_id}/active # Mark as inactive POST /zoho-inventory/inventory/v1/items/{item_id}/inactive ``` ### Contacts #### List Contacts ```bash GET /zoho-inventory/inventory/v1/contacts ``` **Query Parameters:** - `filter_by` - `Status.All`, `Status.Active`, `Status.Inactive`, `Status.Duplicate`, `Status.Crm` - `search_text` - Search across contact fields - `sort_column` - `contact_name`, `first_name`, `last_name`, `email`, `created_time`, `last_modified_time` - `contact_name`, `company_name`, `email`, `phone` - Field-specific filters **Example:** ```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/zoho-inventory/inventory/v1/contacts') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` #### Get Contact ```bash GET /zoho-inventory/inventory/v1/contacts/{contact_id} ``` #### Create Contact ```bash POST /zoho-inventory/inventory/v1/contacts Content-Type: application/json { "contact_name": "Acme Corporation", "contact_type": "customer", "company_name": "Acme Corp", "email": "billing@acme.com", "phone": "+1-555-1234" } ``` **Required Fields:** - `contact_name` - Display name **Optional Fields:** - `contact_type` - `customer` or `vendor` - `company_name` - Legal entity name - `email` - Email address