zoho-inventory（zoho 库存）

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

# List items
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.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://api.maton.ai/zoho-inventory/inventory/v1/{endpoint}

Maton 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:

export MATON_API_KEY="YOUR_API_KEY"

Getting Your API Key

1. Sign in or create an account at maton.ai
2. Go to maton.ai/settings
3. Copy your API key

Connection Management

Manage your Zoho Inventory OAuth connections at https://api.maton.ai.

List Connections

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.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

python <<'EOF'
import urllib.request, os, json
data = json.dumps({'app': 'zoho-inventory'}).encode()
req = urllib.request.Request('https://api.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

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.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:

{
  "connection": {
    "connection_id": "{connection_id}",
    "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

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.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:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/zoho-inventory/inventory/v1/items')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Maton-Connection', '{connection_id}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

If you have multiple connections, always include this header to ensure requests go to the intended account.

Security & Permissions

• Access is scoped to items, sales orders, invoices, purchase orders, bills, contacts, and shipments within the connected Zoho Inventory account.
• All write operations require explicit user approval. Before executing any create, update, or delete call, confirm the target resource and intended effect with the user.

API Reference

Available Modules

Items

List Items

GET /zoho-inventory/inventory/v1/items

Example:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.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:

{
  "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

GET /zoho-inventory/inventory/v1/items/{item_id}

Create Item

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:

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://api.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:

{
  "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

PUT /zoho-inventory/inventory/v1/items/{item_id}
Content-Type: application/json

{
  "name": "Updated Widget",
  "rate": 30.00
}

Delete Item

DELETE /zoho-inventory/inventory/v1/items/{item_id}

Item Status Actions

# 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

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:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.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

GET /zoho-inventory/inventory/v1/contacts/{contact_id}

Create Contact

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
• phone - Phone number
• billing_address - Address object
• shipping_address - Address object
• payment_terms - Days for payment
• currency_id - Currency identifier
• website - Website URL

Update Contact

PUT /zoho-inventory/inventory/v1/contacts/{contact_id}

Delete Contact

DELETE /zoho-inventory/inventory/v1/contacts/{contact_id}

Contact Status Actions

# Mark as active
POST /zoho-inventory/inventory/v1/contacts/{contact_id}/active

# Mark as inactive
POST /zoho-inventory/inventory/v1/contacts/{contact_id}/inactive

Sales Orders

List Sales Orders

GET /zoho-inventory/inventory/v1/salesorders

Example:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/zoho-inventory/inventory/v1/salesorders')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Get Sales Order

GET /zoho-inventory/inventory/v1/salesorders/{salesorder_id}

Create Sales Order

POST /zoho-inventory/inventory/v1/salesorders
Content-Type: application/json

{
  "customer_id": "1234567890000",
  "date": "2026-02-06",
  "line_items": [
    {
      "item_id": "1234567890001",
      "quantity": 5,
      "rate": 25.00
    }
  ]
}

Required Fields:

• customer_id - Customer identifier
• line_items - Array of items with item_id, quantity, rate

Optional Fields:

• salesorder_number - Auto-generated if not specified (do not specify if auto-generation is enabled)
• date - Order date (yyyy-mm-dd)
• shipment_date - Expected shipment date
• reference_number - External reference
• notes - Internal notes
• terms - Terms and conditions
• discount - Discount percentage or amount
• shipping_charge - Shipping cost
• adjustment - Price adjustment

Update Sales Order

PUT /zoho-inventory/inventory/v1/salesorders/{salesorder_id}

Delete Sales Order

DELETE /zoho-inventory/inventory/v1/salesorders/{salesorder_id}

Sales Order Status Actions

# Mark as confirmed
POST /zoho-inventory/inventory/v1/salesorders/{salesorder_id}/status/confirmed

# Mark as void
POST /zoho-inventory/inventory/v1/salesorders/{salesorder_id}/status/void

Invoices

List Invoices

GET /zoho-inventory/inventory/v1/invoices

Example:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/zoho-inventory/inventory/v1/invoices')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Get Invoice

GET /zoho-inventory/inventory/v1/invoices/{invoice_id}

Create Invoice

POST /zoho-inventory/inventory/v1/invoices
Content-Type: application/json

{
  "customer_id": "1234567890000",
  "line_items": [
    {
      "item_id": "1234567890001",
      "quantity": 5,
      "rate": 25.00
    }
  ]
}

Required Fields:

• customer_id - Customer identifier
• line_items - Array of items

Optional Fields:

• invoice_number - Auto-generated if not specified
• date - Invoice date (yyyy-mm-dd)
• due_date - Payment due date
• payment_terms - Days until due
• discount - Discount percentage or amount
• shipping_charge - Shipping cost
• notes - Internal notes
• terms - Terms and conditions

Update Invoice

PUT /zoho-inventory/inventory/v1/invoices/{invoice_id}

Delete Invoice

DELETE /zoho-inventory/inventory/v1/invoices/{invoice_id}

Invoice Status Actions

# Mark as sent
POST /zoho-inventory/inventory/v1/invoices/{invoice_id}/status/sent

# Mark as draft
POST /zoho-inventory/inventory/v1/invoices/{invoice_id}/status/draft

# Void invoice
POST /zoho-inventory/inventory/v1/invoices/{invoice_id}/status/void

Invoice Email

# Email invoice to customer
POST /zoho-inventory/inventory/v1/invoices/{invoice_id}/email

# Get email content template
GET /zoho-inventory/inventory/v1/invoices/{invoice_id}/email

Invoice Payments

# List payments applied
GET /zoho-inventory/inventory/v1/invoices/{invoice_id}/payments

# Delete a payment
DELETE /zoho-inventory/inventory/v1/invoices/{invoice_id}/payments/{invoice_payment_id}

Invoice Credits

# List credits applied
GET /zoho-inventory/inventory/v1/invoices/{invoice_id}/creditsapplied

# Apply credits
POST /zoho-inventory/inventory/v1/invoices/{invoice_id}/credits

# Delete applied credit
DELETE /zoho-inventory/inventory/v1/invoices/{invoice_id}/creditsapplied/{creditnotes_invoice_id}

Invoice Comments

# List comments
GET /zoho-inventory/inventory/v1/invoices/{invoice_id}/comments

# Add comment
POST /zoho-inventory/inventory/v1/invoices/{invoice_id}/comments

# Update comment
PUT /zoho-inventory/inventory/v1/invoices/{invoice_id}/comments/{comment_id}

# Delete comment
DELETE /zoho-inventory/inventory/v1/invoices/{invoice_id}/comments/{comment_id}

Purchase Orders

List Purchase Orders

GET /zoho-inventory/inventory/v1/purchaseorders

Example:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/zoho-inventory/inventory/v1/purchaseorders')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Get Purchase Order

GET /zoho-inventory/inventory/v1/purchaseorders/{purchaseorder_id}

Create Purchase Order

POST /zoho-inventory/inventory/v1/purchaseorders
Content-Type: application/json

{
  "vendor_id": "1234567890000",
  "line_items": [
    {
      "item_id": "1234567890001",
      "quantity": 100,
      "rate": 10.00
    }
  ]
}

Required Fields:

• vendor_id - Vendor identifier
• line_items - Array of items

Optional Fields:

• purchaseorder_number - Auto-generated if not specified (do not specify if auto-generation is enabled)
• date - Order date (yyyy-mm-dd)
• delivery_date - Expected delivery date
• reference_number - External reference
• ship_via - Shipping method
• notes - Internal notes
• terms - Terms and conditions

Update Purchase Order

PUT /zoho-inventory/inventory/v1/purchaseorders/{purchaseorder_id}

Delete Purchase Order

DELETE /zoho-inventory/inventory/v1/purchaseorders/{purchaseorder_id}

Purchase Order Status Actions

# Mark as issued
POST /zoho-inventory/inventory/v1/purchaseorders/{purchaseorder_id}/status/issued

# Mark as cancelled
POST /zoho-inventory/inventory/v1/purchaseorders/{purchaseorder_id}/status/cancelled

Bills

List Bills

GET /zoho-inventory/inventory/v1/bills

Example:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/zoho-inventory/inventory/v1/bills')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Get Bill

GET /zoho-inventory/inventory/v1/bills/{bill_id}

Create Bill

POST /zoho-inventory/inventory/v1/bills
Content-Type: application/json

{
  "vendor_id": "1234567890000",
  "bill_number": "BILL-001",
  "date": "2026-02-06",
  "due_date": "2026-03-06",
  "line_items": [
    {
      "item_id": "1234567890001",
      "quantity": 100,
      "rate": 10.00
    }
  ]
}

Required Fields:

• vendor_id - Vendor identifier
• bill_number - Unique bill number (required, not auto-generated)
• date - Bill date (yyyy-mm-dd)
• due_date - Payment due date
• line_items - Array of items

Optional Fields:

• reference_number - External reference
• notes - Internal notes
• terms - Terms and conditions
• currency_id - Currency identifier
• exchange_rate - Exchange rate for foreign currency

Update Bill

PUT /zoho-inventory/inventory/v1/bills/{bill_id}

Delete Bill

DELETE /zoho-inventory/inventory/v1/bills/{bill_id}

Bill Status Actions

# Mark as open
POST /zoho-inventory/inventory/v1/bills/{bill_id}/status/open

# Mark as void
POST /zoho-inventory/inventory/v1/bills/{bill_id}/status/void

Shipment Orders

Create Shipment Order

POST /zoho-inventory/inventory/v1/shipmentorders
Content-Type: application/json

{
  "shipment_number": "SHP-001",
  "date": "2026-02-06",
  "delivery_method": "FedEx",
  "tracking_number": "1234567890"
}

Required Fields:

• shipment_number - Unique shipment number
• date - Shipment date
• delivery_method - Carrier/delivery method

Optional Fields:

• tracking_number - Carrier tracking number
• shipping_charge - Shipping cost
• notes - Internal notes
• reference_number - External reference

Get Shipment Order

GET /zoho-inventory/inventory/v1/shipmentorders/{shipmentorder_id}

Update Shipment Order

PUT /zoho-inventory/inventory/v1/shipmentorders/{shipmentorder_id}

Delete Shipment Order

DELETE /zoho-inventory/inventory/v1/shipmentorders/{shipmentorder_id}

Mark as Delivered

POST /zoho-inventory/inventory/v1/shipmentorders/{shipmentorder_id}/status/delivered

Item Groups

List Item Groups

GET /zoho-inventory/inventory/v1/itemgroups

Get Item Group

GET /zoho-inventory/inventory/v1/itemgroups/{itemgroup_id}

Create Item Group

POST /zoho-inventory/inventory/v1/itemgroups
Content-Type: application/json

{
  "group_name": "T-Shirts",
  "unit": "pcs",
  "items": [
    {
      "name": "T-Shirt - Small",
      "rate": 20.00,
      "purchase_rate": 8.00,
      "sku": "TS-S"
    },
    {
      "name": "T-Shirt - Medium",
      "rate": 20.00,
      "purchase_rate": 8.00,
      "sku": "TS-M"
    }
  ]
}

Required Fields:

• group_name - Group name
• unit - Unit of measurement

Update Item Group

PUT /zoho-inventory/inventory/v1/itemgroups/{itemgroup_id}

Delete Item Group

DELETE /zoho-inventory/inventory/v1/itemgroups/{itemgroup_id}

Item Group Status Actions

# Mark as active
POST /zoho-inventory/inventory/v1/itemgroups/{itemgroup_id}/active

# Mark as inactive
POST /zoho-inventory/inventory/v1/itemgroups/{itemgroup_id}/inactive

Pagination

Zoho Inventory uses page-based pagination:

GET /zoho-inventory/inventory/v1/items?page=1&per_page=50

Response includes pagination info in page_context:

{
  "code": 0,
  "message": "success",
  "items": [...],
  "page_context": {
    "page": 1,
    "per_page": 50,
    "has_more_page": true,
    "sort_column": "name",
    "sort_order": "A"
  }
}

Continue fetching while has_more_page is true, incrementing page each time.

Code Examples

JavaScript

const response = await fetch(
  'https://api.maton.ai/zoho-inventory/inventory/v1/items',
  {
    headers: {
      'Authorization': `Bearer ${process.env.MATON_API_KEY}`
    }
  }
);
const data = await response.json();

Python

import os
import requests

response = requests.get(
    'https://api.maton.ai/zoho-inventory/inventory/v1/items',
    headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'}
)
data = response.json()

Notes

• All successful responses have code: 0 and a message field
• Dates should be in yyyy-mm-dd format
• Contact types are customer or vendor
• Item types: inventory, sales, purchases, sales_and_purchases
• Product types: goods or service
• The organization_id parameter is automatically handled by the gateway - you do not need to specify it
• Sales order and purchase order numbers are auto-generated by default - do not specify salesorder_number or purchaseorder_number unless auto-generation is disabled in settings
• Status action endpoints use POST method (e.g., /status/confirmed, /status/void)
• Rate limits: 100 requests/minute per organization
• Daily limits vary by plan: Free (1,000), Standard (2,500), Professional (5,000), Premium (7,500), Enterprise (10,000)
• IMPORTANT: When using curl commands, use curl -g when URLs contain brackets to disable glob parsing
• IMPORTANT: When piping curl output to jq or other commands, environment variables like $MATON_API_KEY may not expand correctly in some shell environments

Error Handling

Common Error Codes

Troubleshooting: API Key Issues

1. Check that the MATON_API_KEY environment variable is set:

echo $MATON_API_KEY

1. Verify the API key is valid by listing connections:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.maton.ai/connections')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Troubleshooting: Invalid App Name

1. Ensure your URL path starts with zoho-inventory. For example:

• Correct: https://api.maton.ai/zoho-inventory/inventory/v1/items
• Incorrect: https://api.maton.ai/inventory/v1/items

Resources

• Zoho Inventory API v1 Introduction
• Zoho Inventory Items API
• Zoho Inventory Contacts API
• Zoho Inventory Sales Orders API
• Zoho Inventory Invoices API
• Zoho Inventory Purchase Orders API
• Zoho Inventory Bills API
• Maton Community
• Maton Support