Complete guide to product listing, details, purchase, and license management in Jiffoo Mall

Products API

The Products API provides endpoints for browsing official products, viewing detailed product information, purchasing products, and managing product licenses. All official products are listed through the marketplace endpoints.

Product Lifecycle

sequenceDiagram
    Client->>API: GET /marketplace/products
    API->>Client: Return product list with pagination
    Client->>API: GET /marketplace/products/:slug
    API->>Client: Return detailed product info
    Client->>API: POST /marketplace/products/:slug/purchase
    API->>Client: Return orderId + licenseKey
    Client->>API: POST /marketplace/products/:slug/activate
    API->>Client: Activate license for instance
    Client->>API: GET /marketplace/products/:slug/license/verify
    API->>Client: Return license validation status

Endpoints

List Products

Retrieve a paginated list of official products with optional filtering.

Endpoint: GET /api/marketplace/products

Query Parameters:

Parameter	Type	Required	Description
`category`	string	No	Filter by category (e.g., "enterprise", "addon", "service")
`page`	number	No	Page number (default: 1)
`limit`	number	No	Items per page (default: 20)

Example Request:

curl "https://api.jiffoo.com/api/marketplace/products?category=enterprise&page=1&limit=10"

Response: 200 OK

{
  "products": [
    {
      "id": "jiffoo-enterprise",
      "type": "PRODUCT",
      "slug": "jiffoo-enterprise",
      "name": "Jiffoo Enterprise",
      "description": "Enterprise-grade e-commerce platform with advanced features",
      "shortDescription": "Enterprise-grade e-commerce platform",
      "icon": "/products/enterprise-icon.svg",
      "screenshots": [
        "/products/enterprise-1.png",
        "/products/enterprise-2.png"
      ],
      "pricing": {
        "type": "paid",
        "price": 999,
        "currency": "USD"
      },
      "rating": 4.9,
      "reviewCount": 128,
      "downloadCount": 1500,
      "featured": true,
      "trending": true,
      "createdAt": "2024-01-01T00:00:00.000Z",
      "updatedAt": "2024-12-01T00:00:00.000Z",
      "category": "enterprise",
      "highlights": [
        "Unlimited products",
        "Priority support",
        "Custom integrations",
        "SLA guarantee"
      ]
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 1,
    "totalPages": 1
  },
  "filters": {
    "categories": ["enterprise", "addon", "service"]
  }
}

Error Response: 500 Internal Server Error

{
  "error": "INTERNAL_ERROR",
  "message": "Failed to list products"
}

Get Product Details

Retrieve detailed information about a specific product including features, pricing tiers, and FAQ.

Endpoint: GET /api/marketplace/products/:slug

Path Parameters:

Parameter	Type	Required	Description
`slug`	string	Yes	Product slug identifier

Example Request:

curl "https://api.jiffoo.com/api/marketplace/products/jiffoo-enterprise"

Response: 200 OK

{
  "id": "jiffoo-enterprise",
  "type": "PRODUCT",
  "slug": "jiffoo-enterprise",
  "name": "Jiffoo Enterprise",
  "description": "Enterprise-grade e-commerce platform with advanced features",
  "shortDescription": "Enterprise-grade e-commerce platform",
  "icon": "/products/enterprise-icon.svg",
  "screenshots": [
    "/products/enterprise-1.png",
    "/products/enterprise-2.png"
  ],
  "pricing": {
    "type": "paid",
    "price": 999,
    "currency": "USD"
  },
  "rating": 4.9,
  "reviewCount": 128,
  "downloadCount": 1500,
  "featured": true,
  "trending": true,
  "createdAt": "2024-01-01T00:00:00.000Z",
  "updatedAt": "2024-12-01T00:00:00.000Z",
  "category": "enterprise",
  "highlights": [
    "Unlimited products",
    "Priority support",
    "Custom integrations",
    "SLA guarantee"
  ],
  "fullDescription": "Jiffoo Enterprise is our flagship product for large-scale e-commerce operations.",
  "features": [
    {
      "title": "Scalability",
      "description": "Handle millions of products",
      "items": ["Auto-scaling", "CDN"]
    }
  ],
  "pricingTiers": [
    {
      "id": "starter",
      "name": "Starter",
      "description": "For small teams",
      "price": 299,
      "currency": "USD",
      "billingPeriod": "monthly",
      "features": [
        "Up to 10k products",
        "Email support"
      ]
    },
    {
      "id": "business",
      "name": "Business",
      "description": "For growing businesses",
      "price": 599,
      "currency": "USD",
      "billingPeriod": "monthly",
      "features": [
        "Up to 100k products",
        "Priority support"
      ],
      "highlighted": true
    },
    {
      "id": "enterprise",
      "name": "Enterprise",
      "description": "For large organizations",
      "price": 999,
      "currency": "USD",
      "billingPeriod": "monthly",
      "features": [
        "Unlimited products",
        "Dedicated support",
        "SLA"
      ]
    }
  ],
  "faq": [
    {
      "question": "What is included?",
      "answer": "All enterprise features and priority support."
    }
  ]
}

Error Response: 404 Not Found

{
  "error": "NOT_FOUND",
  "message": "Product not found"
}

Purchase Product

Purchase a product with a specific pricing tier. This endpoint creates an order and generates a license key.

Endpoint: POST /api/marketplace/products/:slug/purchase

Authentication: Optional (user ID will be 'anonymous' if not authenticated)

Path Parameters:

Parameter	Type	Required	Description
`slug`	string	Yes	Product slug identifier

Request Body:

{
  "tierId": "business",
  "paymentMethod": "stripe",
  "billingInfo": {
    "name": "John Doe",
    "email": "[email protected]",
    "company": "Acme Corp"
  }
}

Request Body Parameters:

Parameter	Type	Required	Description
`tierId`	string	Yes	Pricing tier ID from product details
`paymentMethod`	string	Yes	Payment method (e.g., "stripe", "paypal")
`billingInfo`	object	No	Additional billing information

Example Request:

curl -X POST "https://api.jiffoo.com/api/marketplace/products/jiffoo-enterprise/purchase" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{
    "tierId": "business",
    "paymentMethod": "stripe",
    "billingInfo": {
      "name": "John Doe",
      "email": "[email protected]"
    }
  }'

Response: 200 OK

{
  "success": true,
  "orderId": "ORD-A1B2C3D4",
  "licenseKey": "LIC-550E8400-E29B-41D4-A716-446655440000",
  "paymentUrl": null
}

Error Response: 400 Bad Request

{
  "error": "VALIDATION_ERROR",
  "message": "tierId and paymentMethod are required"
}

Error Response: 400 Bad Request

{
  "error": "PURCHASE_FAILED",
  "message": "Product not found"
}

Activate License

Activate a product license for a specific instance. This links the license to your installation.

Endpoint: POST /api/marketplace/products/:slug/activate

Path Parameters:

Parameter	Type	Required	Description
`slug`	string	Yes	Product slug identifier

Request Body:

{
  "licenseKey": "LIC-550E8400-E29B-41D4-A716-446655440000",
  "instanceId": "mystore.example.com"
}

Request Body Parameters:

Parameter	Type	Required	Description
`licenseKey`	string	Yes	License key from purchase
`instanceId`	string	Yes	Unique identifier for your instance (e.g., domain name)

Example Request:

curl -X POST "https://api.jiffoo.com/api/marketplace/products/jiffoo-enterprise/activate" \
  -H "Content-Type: application/json" \
  -d '{
    "licenseKey": "LIC-550E8400-E29B-41D4-A716-446655440000",
    "instanceId": "mystore.example.com"
  }'

Response: 200 OK

{
  "success": true,
  "license": {
    "id": "cm52kg0000000qv0akj8r9w3d",
    "productId": "jiffoo-enterprise",
    "licenseKey": "LIC-550E8400-E29B-41D4-A716-446655440000",
    "type": "subscription",
    "status": "active",
    "features": [],
    "maxInstances": 5,
    "currentInstances": 1,
    "expiresAt": "2025-12-31T23:59:59.000Z",
    "createdAt": "2024-01-01T00:00:00.000Z"
  }
}

Error Response: 400 Bad Request

{
  "error": "VALIDATION_ERROR",
  "message": "licenseKey and instanceId are required"
}

Error Response: 400 Bad Request

{
  "error": "ACTIVATION_FAILED",
  "message": "Invalid or expired license key"
}

Error Response: 400 Bad Request

{
  "error": "ACTIVATION_FAILED",
  "message": "Maximum instances reached"
}

Verify License

Verify if a license is valid for a specific instance.

Endpoint: GET /api/marketplace/products/:slug/license/verify

Path Parameters:

Parameter	Type	Required	Description
`slug`	string	Yes	Product slug identifier

Query Parameters:

Parameter	Type	Required	Description
`licenseKey`	string	Yes	License key to verify
`instanceId`	string	Yes	Instance identifier to check

Example Request:

curl "https://api.jiffoo.com/api/marketplace/products/jiffoo-enterprise/license/verify?licenseKey=LIC-550E8400-E29B-41D4-A716-446655440000&instanceId=mystore.example.com"

Response (Valid License): 200 OK

{
  "valid": true,
  "license": {
    "id": "cm52kg0000000qv0akj8r9w3d",
    "productId": "jiffoo-enterprise",
    "licenseKey": "LIC-550E8400-E29B-41D4-A716-446655440000",
    "type": "subscription",
    "status": "active",
    "features": [],
    "maxInstances": 5,
    "currentInstances": 1,
    "expiresAt": "2025-12-31T23:59:59.000Z",
    "createdAt": "2024-01-01T00:00:00.000Z"
  },
  "features": []
}

Response (Invalid License): 200 OK

{
  "valid": false
}

Error Response: 400 Bad Request

{
  "error": "VALIDATION_ERROR",
  "message": "licenseKey and instanceId are required"
}

Data Models

Product Item

interface ProductItem {
  id: string;
  type: 'PRODUCT';
  slug: string;
  name: string;
  description: string;
  shortDescription: string;
  icon: string;
  screenshots: string[];
  pricing: {
    type: 'free' | 'paid';
    price?: number;
    currency?: string;
  };
  rating: number;
  reviewCount: number;
  downloadCount: number;
  featured: boolean;
  trending: boolean;
  createdAt: string;
  updatedAt: string;
  category: string;
  highlights: string[];
}

Product Detail

Extends ProductItem with additional fields:

interface ProductDetail extends ProductItem {
  fullDescription: string;
  features: FeatureSection[];
  pricingTiers: PricingTier[];
  faq: FAQItem[];
  comparison?: ComparisonTable;
}

interface FeatureSection {
  title: string;
  description: string;
  items: string[];
}

interface PricingTier {
  id: string;
  name: string;
  description: string;
  price: number;
  currency: string;
  billingPeriod?: 'monthly' | 'yearly' | 'one-time';
  features: string[];
  highlighted?: boolean;
}

interface FAQItem {
  question: string;
  answer: string;
}

License Info

interface LicenseInfo {
  id: string;
  productId: string;
  licenseKey: string;
  type: 'perpetual' | 'subscription';
  status: 'active' | 'expired' | 'revoked';
  features: string[];
  maxInstances: number;
  currentInstances: number;
  expiresAt?: string;
  createdAt: string;
}

Error Codes

Code	HTTP Status	Description
`VALIDATION_ERROR`	400	Missing or invalid request parameters
`NOT_FOUND`	404	Product not found
`PURCHASE_FAILED`	400	Product or pricing tier not found
`ACTIVATION_FAILED`	400	Invalid license key or maximum instances reached
`INTERNAL_ERROR`	500	Server error occurred

Usage Examples

Complete Purchase Flow

// 1. Browse products
const productsResponse = await fetch('/api/marketplace/products?category=enterprise');
const { products, pagination } = await productsResponse.json();

// 2. Get product details
const productResponse = await fetch('/api/marketplace/products/jiffoo-enterprise');
const product = await productResponse.json();

// 3. Purchase product
const purchaseResponse = await fetch('/api/marketplace/products/jiffoo-enterprise/purchase', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN'
  },
  body: JSON.stringify({
    tierId: 'business',
    paymentMethod: 'stripe',
    billingInfo: {
      name: 'John Doe',
      email: '[email protected]'
    }
  })
});
const { licenseKey, orderId } = await purchaseResponse.json();

// 4. Activate license
const activateResponse = await fetch('/api/marketplace/products/jiffoo-enterprise/activate', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    licenseKey: licenseKey,
    instanceId: 'mystore.example.com'
  })
});
const { license } = await activateResponse.json();

// 5. Verify license (can be called periodically)
const verifyResponse = await fetch(
  `/api/marketplace/products/jiffoo-enterprise/license/verify?licenseKey=${licenseKey}&instanceId=mystore.example.com`
);
const { valid, features } = await verifyResponse.json();

Python Example

import requests

BASE_URL = "https://api.jiffoo.com/api/marketplace"

# List products
response = requests.get(f"{BASE_URL}/products", params={
    "category": "enterprise",
    "page": 1,
    "limit": 10
})
products = response.json()

# Get product details
product = requests.get(f"{BASE_URL}/products/jiffoo-enterprise").json()

# Purchase product (with authentication)
headers = {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "Content-Type": "application/json"
}
purchase_data = {
    "tierId": "business",
    "paymentMethod": "stripe",
    "billingInfo": {
        "name": "John Doe",
        "email": "[email protected]"
    }
}
purchase = requests.post(
    f"{BASE_URL}/products/jiffoo-enterprise/purchase",
    json=purchase_data,
    headers=headers
).json()

# Activate license
activate_data = {
    "licenseKey": purchase["licenseKey"],
    "instanceId": "mystore.example.com"
}
license_info = requests.post(
    f"{BASE_URL}/products/jiffoo-enterprise/activate",
    json=activate_data
).json()

# Verify license
verify_params = {
    "licenseKey": purchase["licenseKey"],
    "instanceId": "mystore.example.com"
}
verification = requests.get(
    f"{BASE_URL}/products/jiffoo-enterprise/license/verify",
    params=verify_params
).json()

print(f"License valid: {verification['valid']}")

Best Practices

License Management

Store License Keys Securely: Never expose license keys in client-side code or public repositories
Verify Periodically: Implement periodic license verification (e.g., daily) to ensure continued validity
Handle Expiration: Check the expiresAt field and notify users before licenses expire
Track Instances: Monitor currentInstances vs maxInstances to prevent activation failures

Error Handling

async function purchaseProduct(slug, tierId) {
  try {
    const response = await fetch(`/api/marketplace/products/${slug}/purchase`, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${token}`
      },
      body: JSON.stringify({ tierId, paymentMethod: 'stripe' })
    });

    if (!response.ok) {
      const error = await response.json();
      if (error.error === 'PURCHASE_FAILED') {
        // Handle product or tier not found
        console.error('Invalid product or pricing tier');
      } else if (error.error === 'VALIDATION_ERROR') {
        // Handle missing parameters
        console.error('Missing required fields');
      }
      throw new Error(error.message);
    }

    return await response.json();
  } catch (error) {
    console.error('Purchase failed:', error);
    throw error;
  }
}

Pagination

When listing products, implement proper pagination to handle large catalogs:

async function getAllProducts(category) {
  let allProducts = [];
  let page = 1;
  let hasMore = true;

  while (hasMore) {
    const response = await fetch(
      `/api/marketplace/products?category=${category}&page=${page}&limit=20`
    );
    const { products, pagination } = await response.json();

    allProducts = [...allProducts, ...products];
    hasMore = page < pagination.totalPages;
    page++;
  }

  return allProducts;
}

Authentication API - User authentication and token management
Marketplace Overview - Understanding the Jiffoo Mall marketplace
License Management Guide - Detailed guide on managing product licenses
Payment Integration - Integrating payment providers

Products API

On this page