Create Product

Endpoint Details Copied

• Method: POST

• URL: /api/v0/products

• Content-Type: multipart/form-data (for image uploads) or application/json

• Authentication: Required (API Key & Secret)

• Idempotency: Supported (recommended for create operations)

Request Parameters Copied

Required Fields Copied

Optional Fields Copied

Enums Copied

ProductType:

• PRODUCT - Physical or digital product

• SERVICE - Service offering

ProductStatus:

• ACTIVE - Available for purchase

• INACTIVE - Not available for purchase

Supported Currencies:

• USD - US Dollar

• EUR - Euro

• USDC - USD Coin (stablecoin)

• EURC - Euro Coin (stablecoin)

Request Examples Copied

Basic Digital Product Copied

curl -X POST "https://api.devdraft.com/api/v0/products" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET" \
  -H "x-idempotency-key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "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"
  }'

Physical Product with Inventory Copied

curl -X POST "https://api.devdraft.com/api/v0/products" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET" \
  -H "x-idempotency-key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Wireless Headphones",
    "description": "High-quality wireless headphones with noise cancellation and 30-hour battery life.",
    "price": 199.99,
    "currency": "USD",
    "weight": 0.5,
    "unit": "kg",
    "stockCount": 100,
    "quantity": 100,
    "status": "ACTIVE",
    "productType": "PRODUCT"
  }'

Product with Image Upload Copied

curl -X POST "https://api.devdraft.com/api/v0/products" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET" \
  -H "x-idempotency-key: $(uuidgen)" \
  -F "name=Gaming Laptop" \
  -F "description=High-performance gaming laptop with RTX graphics" \
  -F "price=1299.99" \
  -F "currency=USD" \
  -F "images=@/path/to/laptop1.jpg" \
  -F "images=@/path/to/laptop2.jpg" \
  -F "stockCount=25"

Service Product Copied

curl -X POST "https://api.devdraft.com/api/v0/products" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET" \
  -H "x-idempotency-key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Business Consultation",
    "description": "1-hour strategic business consultation with industry experts.",
    "price": 150.00,
    "currency": "USD",
    "productType": "SERVICE",
    "status": "ACTIVE",
    "unit": "hour",
    "quantity": 1
  }'

Response Format Copied

Success Response (201 Created) Copied

{
  "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": [],
  "variations": null,
  "paymentLink": null,
  "walletId": "abcd1234-5678-90ef-ghij-klmnopqrstuv",
  "dateAdded": "2024-01-15T10:30:00.000Z",
  "dateUpdated": "2024-01-15T10:30:00.000Z",
  "app": {
    "id": "app_123456789",
    "name": "My Business App"
  },
  "wallet": {
    "id": "abcd1234-5678-90ef-ghij-klmnopqrstuv",
    "address": "0x742d35Cc6635C0532925a3b8d",
    "blockchain": "ETHEREUM"
  },
  "transactions": []
}

Product with Images Response Copied

{
  "id": "550e8400-e29b-41d4-a716-446655440001",
  "name": "Gaming Laptop",
  "description": "High-performance gaming laptop with RTX graphics",
  "price": 1299.99,
  "currency": "USD",
  "productType": "PRODUCT",
  "status": "ACTIVE",
  "stockCount": 25,
  "images": [
    "https://devdraft-images.s3.amazonaws.com/products/laptop1.jpg",
    "https://devdraft-images.s3.amazonaws.com/products/laptop2.jpg"
  ],
  "weight": null,
  "unit": null,
  "dateAdded": "2024-01-15T10:30:00.000Z",
  "dateUpdated": "2024-01-15T10:30:00.000Z"
}

Error Responses Copied

Validation Error (400 Bad Request) Copied

{
  "statusCode": 400,
  "message": [
    "Product name cannot be empty",
    "Price must be greater than 0",
    "Currency must be a valid 3-letter ISO code"
  ],
  "error": "Bad Request"
}

Authentication Error (401 Unauthorized) Copied

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

Rate Limit Error (429 Too Many Requests) Copied

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

Image Upload Guidelines Copied

Supported Formats Copied

• File Types: JPEG, PNG, WebP, GIF

• Maximum Size: 10MB per image

• Maximum Count: 10 images per product

• Recommended Dimensions: 1200x1200px or larger

Upload Methods Copied

1. Form Data Upload: Include images as files in multipart/form-data request

2. Pre-uploaded URLs: Provide existing image URLs in the images array

Image Processing Copied

• Images are automatically optimized and resized

• Multiple sizes are generated for different use cases

• Images are served via CDN for fast loading

Business Logic Copied

Inventory Management Copied

• Digital Products: stockCount and quantity are optional

• Physical Products: Stock tracking is recommended

• Services: Use quantity for available slots/hours

Wallet Assignment Copied

• Products are automatically linked to your app's default wallet

• If no wallet exists, the product is created without wallet assignment

• Wallet linking enables payment processing and revenue tracking

Currency Handling Copied

• Prices are stored exactly as provided (no conversion)

• Payment processing respects the product's currency setting

• Stablecoin pricing (USDC/EURC) provides price stability

Integration Tips Copied

Product Organization Copied

// Group products by type for better management
const productTypes = {
  digital: { productType: 'PRODUCT', type: 'DIGITAL' },
  physical: { productType: 'PRODUCT', type: 'PHYSICAL' },
  service: { productType: 'SERVICE' }
};

Bulk Product Creation Copied

// Use idempotency keys for safe bulk operations
const products = await Promise.all(
  productData.map(product => 
    createProduct({
      ...product,
      idempotencyKey: generateUUID()
    })
  )
);

Image Management Copied

// Upload images after product creation if needed
if (productId && imageFiles.length > 0) {
  await uploadProductImages(productId, imageFiles);
}

Next Steps Copied

After creating a product, you can:

1. Add to Payment Links: Include products in payment link configurations

2. Create Invoices: Add products to customer invoices

3. Upload Additional Images: Use the product images endpoint

4. Update Product Details: Modify pricing, inventory, or descriptions

5. Track Sales: Monitor product performance through transaction reports

For more information, see:

• Update Product Documentation

• Product Images Management

• Payment Links with Products

• Invoice Product Integration