Products
/List Products
List Products
Retrieve a paginated list of all products in your inventory with filtering and sorting options.
GET
/v1/productsReturns a paginated list of products with optional filtering, sorting, and search functionality.
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| limit | integer | - | Number of products to return (1-100, default: 20) |
| offset | integer | - | Number of products to skip (default: 0) |
| search | string | - | Search in product name, description, or SKU |
| category | string | - | Filter by product category |
| status | string | - | Filter by status: active, inactive, archived |
| sort_by | string | - | Sort field: name, created_at, price, stock |
| sort_order | string | - | Sort direction: asc, desc (default: asc) |
Examples
Basic Request
Get the first 20 products
curl -X GET "https://api.magentod.com/v1/products" \
-H "Authorization: Bearer mgd_live_sk_1234567890abcdef" \
-H "Content-Type: application/json"Advanced Request with Filters
Search for active electronics products, sorted by price
curl -X GET "https://api.magentod.com/v1/products?search=phone&category=Electronics&status=active&sort_by=price&sort_order=desc&limit=10" \
-H "Authorization: Bearer mgd_live_sk_1234567890abcdef" \
-H "Content-Type: application/json"JavaScript Implementation
const getProducts = async (filters = {}) => {
const params = new URLSearchParams({
limit: 20,
offset: 0,
...filters
});
const response = await fetch(`https://api.magentod.com/v1/products?${params}`, {
method: 'GET',
headers: {
'Authorization': 'Bearer mgd_live_sk_1234567890abcdef',
'Content-Type': 'application/json'
}
});
if (!response.ok) {
throw new Error(`HTTP error! status: ${response.status}`);
}
return await response.json();
};
// Usage examples
const allProducts = await getProducts();
const searchResults = await getProducts({ search: 'iPhone', category: 'Electronics' });
const sortedProducts = await getProducts({ sort_by: 'price', sort_order: 'desc' });Response
Success Response (200 OK)
{
"data": [
{
"id": "prod_1234567890",
"name": "iPhone 15 Pro",
"sku": "IPHONE15PRO-128-BLACK",
"description": "iPhone 15 Pro 128GB Black",
"price": 15999000,
"cost": 12000000,
"category": "Electronics",
"brand": "Apple",
"weight": 187,
"dimensions": {
"length": 146.6,
"width": 70.6,
"height": 8.25
},
"stock": {
"quantity": 50,
"min_quantity": 10,
"track_quantity": true,
"locations": [
{
"warehouse_id": "wh_main",
"quantity": 30
},
{
"warehouse_id": "wh_secondary",
"quantity": 20
}
]
},
"status": "active",
"images": [
"https://cdn.magentod.com/products/iphone15pro-black-1.jpg"
],
"metadata": {
"color": "Black",
"storage": "128GB",
"model": "A3106"
},
"created_at": "2024-01-15T08:30:00Z",
"updated_at": "2024-01-15T10:15:00Z"
}
// ... more products
],
"pagination": {
"total": 1247,
"count": 20,
"limit": 20,
"offset": 0,
"has_more": true,
"next_offset": 20
},
"filters": {
"search": null,
"category": null,
"status": null,
"sort_by": "name",
"sort_order": "asc"
}
}Response Fields
| Field | Type | Description |
|---|---|---|
| data | array | Array of product objects |
| pagination.total | integer | Total number of products matching filters |
| pagination.count | integer | Number of products in current page |
| pagination.has_more | boolean | Whether there are more products to fetch |
| filters | object | Applied filters and sorting options |
Error Responses
400 Bad Request
Invalid query parameters
{
"error": {
"code": "invalid_parameter",
"message": "Invalid sort_by value. Must be one of: name, created_at, price, stock",
"param": "sort_by"
}
}401 Unauthorized
Invalid or missing API key
{
"error": {
"code": "authentication_failed",
"message": "Invalid API key provided",
"type": "authentication_error"
}
}Best Practices
Use Pagination
Always use limit and offset parameters to avoid loading too much data at once.
Filter Early
Use category and status filters to reduce the amount of data transferred and processed.
Cache Results
Cache product lists on your end to reduce API calls and improve performance.
Handle Errors Gracefully
Always check response status and handle error cases appropriately.
Related Endpoints
Explore other product management endpoints