List Products

The List Products endpoints enable you to retrieve product information from your catalog. You can either fetch all products with pagination support or retrieve a specific product by its ID. These endpoints provide comprehensive product details including pricing, inventory, images, and transaction history.

Endpoint DetailsCopied!

List All Products

Method: GET
URL: /api/v0/products
Authentication: Required (API Key & Secret)
Rate Limiting: 1000 requests per minute

Fetch Single Product

Method: GET
URL: /api/v0/products/{id}
Authentication: Required (API Key & Secret)
Rate Limiting: 1000 requests per minute

List Products ParametersCopied!

Query Parameters

Parameter	Type	Required	Description	Default	Example
`skip`	integer	No	Number of records to skip for pagination	`0`	`20`
`take`	integer	No	Number of records to return (max 100)	`10`	`50`

Pagination Guidelines

Maximum per request: 100 products
Default page size: 10 products
Offset-based pagination: Use skip and take parameters
Total count: Not included in response (use separate count endpoint if needed)

Single Product ParametersCopied!

Path Parameters

Parameter	Type	Required	Description	Example
`id`	string (UUID)	Yes	Unique product identifier	`550e8400-e29b-41d4-a716-446655440000`

Request ExamplesCopied!

List All Products (Default Pagination)

curl -X GET "https://api.devdraft.com/api/v0/products" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET"

List Products with Pagination

curl -X GET "https://api.devdraft.com/api/v0/products?skip=20&take=50" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET"

Fetch Single Product

curl -X GET "https://api.devdraft.com/api/v0/products/550e8400-e29b-41d4-a716-446655440000" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET"

JavaScript/Node.js Example

// Fetch products with pagination
const fetchProducts = async (skip = 0, take = 10) => {
  const response = await fetch(`https://api.devdraft.com/api/v0/products?skip=${skip}&take=${take}`, {
    method: 'GET',
    headers: {
      'x-client-key': 'YOUR_CLIENT_KEY',
      'x-client-secret': 'YOUR_CLIENT_SECRET'
    }
  });
  
  if (!response.ok) {
    throw new Error(`HTTP error! status: ${response.status}`);
  }
  
  return await response.json();
};

// Fetch single product
const fetchProduct = async (productId) => {
  const response = await fetch(`https://api.devdraft.com/api/v0/products/${productId}`, {
    method: 'GET',
    headers: {
      'x-client-key': 'YOUR_CLIENT_KEY',
      'x-client-secret': 'YOUR_CLIENT_SECRET'
    }
  });
  
  if (!response.ok) {
    throw new Error(`HTTP error! status: ${response.status}`);
  }
  
  return await response.json();
};

// Usage examples
try {
  // Get first 20 products
  const products = await fetchProducts(0, 20);
  console.log(`Found ${products.length} products`);
  
  // Get specific product
  const product = await fetchProduct('550e8400-e29b-41d4-a716-446655440000');
  console.log(`Product: ${product.name}`);
} catch (error) {
  console.error('Error fetching products:', error);
}

Response FormatCopied!

List Products Response (200 OK)

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Premium Software License",
    "description": "Annual license for our premium software suite with advanced features, priority support, and regular updates.",
    "price": 299.99,
    "currency": "USD",
    "productType": "PRODUCT",
    "status": "ACTIVE",
    "stockCount": null,
    "quantity": null,
    "weight": null,
    "unit": null,
    "images": [
      "https://devdraft-images.s3.amazonaws.com/products/software-license.jpg"
    ],
    "variations": null,
    "paymentLink": "https://pay.devdraft.com/p/premium-license",
    "walletId": "abcd1234-5678-90ef-ghij-klmnopqrstuv",
    "dateAdded": "2024-01-15T10:30:00.000Z",
    "dateUpdated": "2024-01-15T10:30:00.000Z",
    "wallet": {
      "id": "abcd1234-5678-90ef-ghij-klmnopqrstuv",
      "address": "0x742d35Cc6635C0532925a3b8d",
      "blockchain": "ETHEREUM",
      "type": "APP"
    },
    "transactions": []
  },
  {
    "id": "550e8400-e29b-41d4-a716-446655440001",
    "name": "Wireless Headphones",
    "description": "High-quality wireless headphones with noise cancellation and 30-hour battery life.",
    "price": 199.99,
    "currency": "USD",
    "productType": "PRODUCT",
    "status": "ACTIVE",
    "stockCount": 85,
    "quantity": 100,
    "weight": 0.5,
    "unit": "kg",
    "images": [
      "https://devdraft-images.s3.amazonaws.com/products/headphones-1.jpg",
      "https://devdraft-images.s3.amazonaws.com/products/headphones-2.jpg"
    ],
    "variations": [
      {
        "id": "var_001",
        "type": "Color",
        "options": [
          { "name": "Black", "value": "black", "priceAdjustment": 0 },
          { "name": "White", "value": "white", "priceAdjustment": 0 },
          { "name": "Blue", "value": "blue", "priceAdjustment": 10 }
        ]
      }
    ],
    "paymentLink": "https://pay.devdraft.com/p/wireless-headphones",
    "walletId": "abcd1234-5678-90ef-ghij-klmnopqrstuv",
    "dateAdded": "2024-01-14T14:20:00.000Z",
    "dateUpdated": "2024-01-16T09:15:00.000Z",
    "wallet": {
      "id": "abcd1234-5678-90ef-ghij-klmnopqrstuv",
      "address": "0x742d35Cc6635C0532925a3b8d",
      "blockchain": "ETHEREUM",
      "type": "APP"
    },
    "transactions": [
      {
        "id": "txn_123456789",
        "amount": 199.99,
        "currency": "USD",
        "status": "PAYMENT_PROCESSED",
        "dateCreated": "2024-01-16T09:15:00.000Z"
      }
    ]
  }
]

Single Product Response (200 OK)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Premium Software License",
  "description": "Annual license for our premium software suite with advanced features, priority support, and regular updates.",
  "price": 299.99,
  "currency": "USD",
  "productType": "PRODUCT",
  "status": "ACTIVE",
  "stockCount": null,
  "quantity": null,
  "weight": null,
  "unit": null,
  "images": [
    "https://devdraft-images.s3.amazonaws.com/products/software-license.jpg"
  ],
  "variations": null,
  "paymentLink": "https://pay.devdraft.com/p/premium-license",
  "walletId": "abcd1234-5678-90ef-ghij-klmnopqrstuv",
  "dateAdded": "2024-01-15T10:30:00.000Z",
  "dateUpdated": "2024-01-15T10:30:00.000Z",
  "wallet": {
    "id": "abcd1234-5678-90ef-ghij-klmnopqrstuv",
    "address": "0x742d35Cc6635C0532925a3b8d",
    "blockchain": "ETHEREUM",
    "type": "APP"
  },
  "transactions": []
}

Empty Response (200 OK)

[]

Response FieldsCopied!

Product Object Fields

Field	Type	Description	Example
`id`	string	Unique product identifier	`"550e8400-e29b-41d4-a716-446655440000"`
`name`	string	Product name	`"Premium Software License"`
`description`	string	Product description	`"Annual license for..."`
`price`	number	Product price	`299.99`
`currency`	string	Currency code	`"USD"`
`productType`	enum	Product category (`PRODUCT`, `SERVICE`)	`"PRODUCT"`
`status`	enum	Product status (`ACTIVE`, `INACTIVE`)	`"ACTIVE"`
`stockCount`	number\|null	Current stock level	`85`
`quantity`	number\|null	Available quantity	`100`
`weight`	number\|null	Product weight	`0.5`
`unit`	string\|null	Unit of measurement	`"kg"`
`images`	array	Product image URLs	`["https://..."]`
`variations`	array\|null	Product variations/options	See variation object
`paymentLink`	string\|null	Direct payment URL	`"https://pay.devdraft.com/p/..."`
`walletId`	string\|null	Associated wallet ID	`"abcd1234-..."`
`dateAdded`	string	Creation timestamp (ISO 8601)	`"2024-01-15T10:30:00.000Z"`
`dateUpdated`	string\|null	Last update timestamp	`"2024-01-16T09:15:00.000Z"`
`wallet`	object\|null	Wallet details	See wallet object
`transactions`	array	Related transactions	See transaction object

Variation Object Fields

Field	Type	Description	Example
`id`	string	Variation identifier	`"var_001"`
`type`	string	Variation type	`"Color"`
`options`	array	Available options	See option object

Option Object Fields

Field	Type	Description	Example
`name`	string	Option display name	`"Black"`
`value`	string	Option value	`"black"`
`priceAdjustment`	number	Price modifier	`10`

Error ResponsesCopied!

Product Not Found (404 Not Found)

{
  "statusCode": 404,
  "message": "Product not found",
  "error": "Not Found"
}

Invalid Product ID (400 Bad Request)

{
  "statusCode": 400,
  "message": "Invalid product ID format",
  "error": "Bad Request"
}

Authentication Error (401 Unauthorized)

{
  "statusCode": 401,
  "message": "Invalid or missing API credentials",
  "error": "Unauthorized"
}

Rate Limit Error (429 Too Many Requests)

{
  "statusCode": 429,
  "message": "Rate limit exceeded. Maximum 1000 requests per minute.",
  "error": "Too Many Requests",
  "retryAfter": 60
}

Invalid Pagination Parameters (400 Bad Request)

{
  "statusCode": 400,
  "message": "Take parameter cannot exceed 100",
  "error": "Bad Request"
}

Usage PatternsCopied!

Pagination Implementation

// Implement efficient pagination
class ProductPaginator {
  constructor(apiClient) {
    this.apiClient = apiClient;
    this.pageSize = 50;
  }

  async getAllProducts() {
    let skip = 0;
    let allProducts = [];
    let hasMore = true;

    while (hasMore) {
      const products = await this.apiClient.fetchProducts(skip, this.pageSize);
      allProducts = allProducts.concat(products);
      
      hasMore = products.length === this.pageSize;
      skip += this.pageSize;
      
      // Prevent infinite loops
      if (skip > 10000) break;
    }

    return allProducts;
  }

  async getProductsPage(page = 1) {
    const skip = (page - 1) * this.pageSize;
    return await this.apiClient.fetchProducts(skip, this.pageSize);
  }
}

Product Filtering & Search

// Client-side filtering (for small datasets)
const filterProducts = (products, criteria) => {
  return products.filter(product => {
    // Filter by status
    if (criteria.status && product.status !== criteria.status) return false;
    
    // Filter by product type
    if (criteria.productType && product.productType !== criteria.productType) return false;
    
    // Filter by price range
    if (criteria.minPrice && product.price < criteria.minPrice) return false;
    if (criteria.maxPrice && product.price > criteria.maxPrice) return false;
    
    // Filter by availability
    if (criteria.inStock && product.stockCount !== null && product.stockCount <= 0) return false;
    
    // Search by name/description
    if (criteria.search) {
      const searchTerm = criteria.search.toLowerCase();
      const nameMatch = product.name.toLowerCase().includes(searchTerm);
      const descMatch = product.description.toLowerCase().includes(searchTerm);
      if (!nameMatch && !descMatch) return false;
    }
    
    return true;
  });
};

// Usage
const criteria = {
  status: 'ACTIVE',
  productType: 'PRODUCT',
  minPrice: 50,
  maxPrice: 500,
  inStock: true,
  search: 'wireless'
};

const filteredProducts = filterProducts(allProducts, criteria);

Product Cache Management

// Implement caching for better performance
class ProductCache {
  constructor(ttl = 300000) { // 5 minutes default TTL
    this.cache = new Map();
    this.ttl = ttl;
  }

  async getProducts(skip = 0, take = 10) {
    const key = `products_${skip}_${take}`;
    const cached = this.cache.get(key);
    
    if (cached && Date.now() - cached.timestamp < this.ttl) {
      return cached.data;
    }

    const products = await fetchProducts(skip, take);
    this.cache.set(key, {
      data: products,
      timestamp: Date.now()
    });

    return products;
  }

  async getProduct(id) {
    const key = `product_${id}`;
    const cached = this.cache.get(key);
    
    if (cached && Date.now() - cached.timestamp < this.ttl) {
      return cached.data;
    }

    const product = await fetchProduct(id);
    this.cache.set(key, {
      data: product,
      timestamp: Date.now()
    });

    return product;
  }

  invalidate(pattern = null) {
    if (pattern) {
      for (const key of this.cache.keys()) {
        if (key.includes(pattern)) {
          this.cache.delete(key);
        }
      }
    } else {
      this.cache.clear();
    }
  }
}

Performance OptimizationCopied!

Recommended Practices

Use Appropriate Page Sizes:
- Small pages (10-20) for UI pagination
- Larger pages (50-100) for bulk operations
Implement Caching:
- Cache frequently accessed products
- Set reasonable TTL (5-15 minutes)
- Invalidate cache on updates
Lazy Loading:
- Load product details on demand
- Use list endpoint for browsing
- Fetch individual products when needed
Batch Operations:
- Minimize API calls by fetching multiple products
- Use pagination efficiently

Integration ExamplesCopied!

E-commerce Catalog

// Build product catalog with categories
const buildCatalog = async () => {
  const allProducts = await getAllProducts();
  
  const catalog = {
    digital: allProducts.filter(p => p.productType === 'PRODUCT' && !p.weight),
    physical: allProducts.filter(p => p.productType === 'PRODUCT' && p.weight),
    services: allProducts.filter(p => p.productType === 'SERVICE'),
    active: allProducts.filter(p => p.status === 'ACTIVE'),
    inStock: allProducts.filter(p => !p.stockCount || p.stockCount > 0)
  };
  
  return catalog;
};

Inventory Dashboard

// Monitor inventory levels
const getInventoryStatus = async () => {
  const products = await getAllProducts();
  
  return {
    total: products.length,
    active: products.filter(p => p.status === 'ACTIVE').length,
    outOfStock: products.filter(p => p.stockCount === 0).length,
    lowStock: products.filter(p => p.stockCount > 0 && p.stockCount < 10).length,
    totalValue: products.reduce((sum, p) => sum + (p.price * (p.stockCount || 0)), 0)
  };
};

Next StepsCopied!

After fetching products, you can:

Display in Catalog: Show products in your e-commerce interface
Update Product Details: Modify product information as needed
Add to Payment Links: Include products in payment workflows
Track Performance: Analyze product sales and popularity
Manage Inventory: Monitor stock levels and reorder points

For more information, see: