n8n-nodes-opencart

A comprehensive n8n node for OpenCart API integration, providing full CRUD operations and webhook support for e-commerce automation workflows.

Features

🚀 Comprehensive API Coverage

Products: Full CRUD operations with categories, attributes, options, images
Categories: Hierarchical category management
Customers: Customer profiles, addresses, groups
Orders: Order management, status updates, history tracking
Manufacturers: Brand and manufacturer data
Options & Filters: Product variations and filtering
Reviews & Wishlists: Customer feedback and preferences
Coupons & Vouchers: Discount code management
Geographic Data: Countries, zones, currencies, languages
Store Management: Multi-store configurations
Content Pages: Information pages and downloads
Returns & Rewards: Customer service and loyalty programs

🔐 Flexible Authentication

API Key Authentication: Secure key-based access
OAuth 2.0: Modern token-based authentication
Multi-version Support: OpenCart 3.x and 4.x compatibility

⚡ Advanced Features

Batch Operations: Process multiple records efficiently
Pagination Support: Handle large datasets with automatic pagination
Filtering & Sorting: Advanced query capabilities
Retry Logic: Exponential backoff for failed requests
Error Handling: Comprehensive error reporting and recovery
Rate Limiting: Respect API limits and quotas
Webhook Support: Real-time event notifications

Installation

From npm Registry

npm install n8n-nodes-opencart

From Source

git clone https://github.com/kilocode/n8n-nodes-opencart.git
cd n8n-nodes-opencart
npm install
npm run build
npm link

In n8n

Install the package in your n8n installation directory
Restart n8n
The OpenCart node will be available in the node palette

Configuration

API Key Authentication

In your OpenCart admin panel, go to System → Users → API
Create or edit an API user
Generate an API key
Configure the credentials in n8n:
- Base URL: https://your-store.com (without trailing slash)
- API Version: Select your OpenCart version (3.x or 4.x)
- Authentication Method: API Key
- API Key: Your generated API key

OAuth 2.0 Authentication

Set up OAuth 2.0 in your OpenCart installation
Create OAuth client credentials
Configure in n8n:
- Base URL: https://your-store.com
- API Version: Select your OpenCart version
- Client ID: Your OAuth client ID
- Client Secret: Your OAuth client secret
- Scope: read write (or specific scopes as needed)

Usage Examples

Get All Products with Filtering

// Node configuration
Resource: Products
Operation: Get All
Additional Fields:
  - Filter Name: "laptop"
  - Filter Status: Enabled
  - Sort By: name
  - Sort Order: ASC
  - Limit: 50

Create New Product

{
  "name": "Gaming Laptop",
  "description": "High-performance gaming laptop",
  "model": "GL-2023",
  "price": "1299.99",
  "quantity": "10",
  "status": "1",
  "categories": ["laptops", "gaming"],
  "manufacturer_id": "5"
}

Batch Operations

// Create multiple products at once
[
  {
    "operation": "create",
    "data": {
      "name": "Product 1",
      "price": "99.99",
      "model": "P1-2023"
    }
  },
  {
    "operation": "update", 
    "id": "123",
    "data": {
      "price": "89.99"
    }
  },
  {
    "operation": "delete",
    "id": "456"
  }
]

Order Management Workflow

// 1. Get pending orders
Resource: Orders
Operation: Get All
Filters: 
  - filter_order_status_id: "1" // Pending status

// 2. Update order status
Resource: Orders  
Operation: Update
Resource ID: "{{$json.order_id}}"
Data: {
  "order_status_id": "2", // Processing
  "comment": "Order confirmed and processing started",
  "notify": "1"
}

// 3. Send notification email (via Email node)

API Endpoints Reference

Products API

Get All Products

Method: GET /api/products
Parameters:
- page: Page number
- limit: Results per page
- sort: Sort field
- order: Sort direction (ASC/DESC)
- filter_name: Filter by name
- filter_status: Filter by status
- filter_category_id: Filter by category

Get Single Product

Method: GET /api/products/{id}
Response: Full product details with options, images, categories

Create Product

Method: POST /api/products
Required Fields: name, model, price
Optional Fields: description, categories, manufacturer_id, images, options

Update Product

Method: PUT /api/products/{id}
Body: Product fields to update

Delete Product

Method: DELETE /api/products/{id}

Orders API

Get All Orders

Method: GET /api/orders
Parameters:
- filter_order_id: Filter by order ID
- filter_customer: Filter by customer name
- filter_order_status_id: Filter by status
- filter_date_from: Filter by date range
- filter_date_to: Filter by date range

Get Order Details

Method: GET /api/orders/{id}
Response: Complete order with products, totals, history

Update Order Status

Method: PUT /api/orders/{id}
Body:

{
  "order_status_id": "2",
  "comment": "Status updated",
  "notify": "1"
}

Customers API

Get All Customers

Method: GET /api/customers
Parameters: Standard filtering and pagination

Get Customer Details

Method: GET /api/customers/{id}
Response: Customer profile with addresses, orders

Create Customer

Method: POST /api/customers
Required: firstname, lastname, email, password

Categories API

Get Category Tree

Method: GET /api/categories
Response: Hierarchical category structure

Create Category

Method: POST /api/categories
Required: name, parent_id

Webhook Integration

Webhook Events

The node supports real-time webhooks for:

order.created: New order placed
order.updated: Order status changed
product.created: New product added
product.updated: Product modified
customer.created: New customer registered

Webhook Configuration

Set up webhook endpoint in your OpenCart module
Configure webhook URL in n8n workflow
Handle incoming webhook data:

// Webhook payload example
{
  "event": "order.created",
  "data": {
    "order_id": "123",
    "customer_email": "customer@example.com", 
    "total": "99.99",
    "status": "pending"
  },
  "timestamp": "2023-12-01T10:00:00Z"
}

Error Handling

Common Error Codes

401 Unauthorized: Invalid API credentials
403 Forbidden: Insufficient permissions
404 Not Found: Resource doesn't exist
422 Validation Error: Invalid data provided
429 Rate Limited: Too many requests
500 Server Error: OpenCart server error

Error Response Format

{
  "error": true,
  "message": "Product not found",
  "code": "PRODUCT_NOT_FOUND",
  "details": {
    "product_id": "999"
  }
}

Retry Configuration

The node automatically retries failed requests with exponential backoff:

Default Retries: 3 attempts
Base Delay: 1000ms
Backoff Multiplier: 2x
Max Delay: 30 seconds

Performance Optimization

Batch Processing

Use batch operations for:

Bulk product imports
Mass price updates
Multiple order processing
Category restructuring

Pagination Best Practices

Use reasonable page sizes (50-100 records)
Process pages sequentially for data consistency
Implement progress tracking for large datasets

Rate Limiting

Respect OpenCart server limits (typically 60 requests/minute)
Implement delays between requests if needed
Use batch operations to reduce total API calls

Troubleshooting

Connection Issues

Verify base URL is correct and accessible
Check API credentials are valid
Ensure OpenCart API is enabled
Verify SSL certificate if using HTTPS

Authentication Problems

Confirm API user has proper permissions
Check API key hasn't expired
Verify OAuth scopes are sufficient
Test credentials with simple GET request

Data Issues

Validate JSON data format
Check required fields are provided
Verify field value constraints
Review OpenCart logs for detailed errors

Performance Issues

Reduce batch sizes if timeout errors occur
Increase timeout values for large operations
Implement pagination for large datasets
Consider off-peak processing for bulk operations

Development

Local Development

git clone https://github.com/kilocode/n8n-nodes-opencart.git
cd n8n-nodes-opencart
npm install
npm run dev

Building

npm run build

Testing

# Run all tests
npm test

# Run with coverage
npm run test:coverage

# Run integration tests (requires OpenCart instance)
npm run test:integration

Contributing

Fork the repository
Create feature branch (git checkout -b feature/amazing-feature)
Commit changes (git commit -m 'Add amazing feature')
Push to branch (git push origin feature/amazing-feature)
Open Pull Request

Compatibility

OpenCart Versions

✅ OpenCart 3.0.x
✅ OpenCart 3.1.x
✅ OpenCart 4.0.x
⏳ OpenCart 4.1.x (coming soon)

n8n Versions

✅ n8n 0.200.0+
✅ n8n 1.0.0+

Node.js Versions

✅ Node.js 16.x
✅ Node.js 18.x
✅ Node.js 20.x

Support

Documentation

Community

Commercial Support

For enterprise support, custom development, or consulting services:

Email: contact@kilocode.com
Website: https://kilocode.com

License

MIT License - see LICENSE file for details.

Changelog

v1.0.0 (2023-12-01)

🎉 Initial release
✅ Complete CRUD operations for all OpenCart resources
✅ API Key and OAuth 2.0 authentication
✅ Batch operations support
✅ Comprehensive error handling and retry logic
✅ Pagination and filtering capabilities
✅ Webhook integration
✅ OpenCart 3.x and 4.x support
✅ Full TypeScript implementation
✅ 90%+ test coverage

Made with ❤️ by Kilo Code

Name		Name	Last commit message	Last commit date
credentials		credentials
icons		icons
nodes/OpenCart		nodes/OpenCart
types		types
.eslintrc.prepublish.js		.eslintrc.prepublish.js
.gitignore		.gitignore
DEPLOYMENT.md		DEPLOYMENT.md
NPM_PUBLISHING.md		NPM_PUBLISHING.md
README.md		README.md
gulpfile.js		gulpfile.js
install.sh		install.sh
package.json		package.json
tsconfig.json		tsconfig.json

Latest commit

History

Folders and files

Repository files navigation