API Reference

Complete API documentation for BrainPredict Commerce with endpoints, parameters, and response examples.

Authentication

All API requests require authentication using your API key in the Authorization header:

Authorization: Bearer bp_commerce_live_your_api_key_here

Base URL

https://api.brainpredict.ai/v1/commerce

Endpoints

POST/api/commerce/recommend-bundle

Generate intelligent product bundle recommendations using association rule mining and collaborative filtering

Endpoints

Parameters:

product_idcustomer_segmenttransaction_history

Example Response:

{
  "success": true,
  "model": "BundleOptimizer",
  "accuracy": 94.2,
  "prediction": {
    "bundle_id": "bundle_123",
    "product_ids": [
      "prod_A",
      "prod_B",
      "prod_C"
    ],
    "confidence": 0.92,
    "expected_uplift": 0.25
  }
}

POST/api/commerce/allocate-inventory

Optimize inventory allocation across locations using demand forecasting and optimization algorithms

Endpoints

Parameters:

sku_idavailable_quantitylocationsdemand_forecast

Example Response:

{
  "success": true,
  "model": "InventoryAllocationAI",
  "accuracy": 93.8,
  "prediction": {
    "allocation_plan": {
      "location_1": 200,
      "location_2": 150
    },
    "optimization_score": 0.89
  }
}

POST/api/commerce/predict-return-risk

Predict return probability for orders and identify high-risk products

Endpoints

Parameters:

order_idcustomer_idproduct_idsorder_value

Example Response:

{
  "success": true,
  "model": "ReturnPredictor",
  "accuracy": 91.5,
  "prediction": {
    "return_probability": 0.15,
    "risk_level": "low",
    "high_risk_products": []
  }
}

POST/api/commerce/optimize-loyalty

Optimize loyalty program rewards and tier progression for maximum engagement

Endpoints

Parameters:

customer_idcurrent_tierpurchase_historyengagement_data

Example Response:

{
  "success": true,
  "model": "LoyaltyOptimizer",
  "accuracy": 92.7,
  "prediction": {
    "recommended_rewards": [
      "10% discount",
      "free shipping"
    ],
    "tier_progression_path": "silver_to_gold",
    "engagement_score": 0.85
  }
}

POST/api/commerce/hyper-personalize

Generate hyper-personalized shopping experiences based on context, behavior, and preferences

Endpoints

Parameters:

customer_idcontextbrowsing_historypreferences

Example Response:

{
  "success": true,
  "model": "HyperPersonalizationEngine",
  "accuracy": 95.1,
  "prediction": {
    "personalized_homepage": {
      "featured_products": [
        "prod_X",
        "prod_Y"
      ]
    },
    "personalization_score": 0.93
  }
}

POST/api/commerce/process-voice-command

Process voice commands for voice commerce interactions

Endpoints

Parameters:

customer_idvoice_inputcontext

Example Response:

{
  "success": true,
  "model": "VoiceCommerceAI",
  "accuracy": 89.3,
  "prediction": {
    "intent": "search_product",
    "entities": {
      "product_category": "shoes",
      "size": "42"
    },
    "action": "show_products"
  }
}

POST/api/commerce/ar-session

Analyze AR/VR shopping sessions and provide product recommendations

Endpoints

Parameters:

customer_idproduct_idsession_data

Example Response:

{
  "success": true,
  "model": "ARVRShoppingIntelligence",
  "accuracy": 90.8,
  "prediction": {
    "engagement_score": 0.87,
    "purchase_intent": 0.72,
    "recommended_products": [
      "prod_Z"
    ]
  }
}

POST/api/commerce/optimize-subscription

Optimize subscription pricing, billing cycles, and retention strategies

Endpoints

Parameters:

customer_idsubscription_idusage_databilling_history

Example Response:

{
  "success": true,
  "model": "SubscriptionOptimizationAI",
  "accuracy": 93.4,
  "prediction": {
    "optimal_price": 29.99,
    "recommended_billing_cycle": "monthly",
    "churn_risk": 0.12
  }
}

POST/api/v1/commerce/strategic/benchmarking/performance

Benchmark commerce performance against industry standards and identify optimization opportunities

Endpoints

Parameters:

organization_dataindustrytime_period_days

Example Response:

{
  "benchmarking_results": {
    "conversion_rate": {
      "value": 2.5,
      "industry_avg": 2.1,
      "percentile": 65
    },
    "average_order_value": {
      "value": 85.5,
      "industry_avg": 75,
      "percentile": 72
    }
  },
  "performance_gaps": [
    "cart_abandonment_rate"
  ],
  "recommendations": [
    "Implement cart recovery emails",
    "Optimize checkout flow"
  ]
}

POST/api/v1/commerce/strategic/intelligence/aggregate

Aggregate insights across all commerce data for strategic decision-making

Endpoints

Parameters:

time_period_daysinclude_predictionsaggregation_level

Example Response:

{
  "aggregated_intelligence": {
    "total_revenue": 1250000,
    "total_orders": 15000,
    "average_order_value": 83.33
  },
  "key_insights": [
    "Revenue up 15% vs last period",
    "Mobile conversion improving"
  ],
  "strategic_recommendations": [
    "Invest in mobile optimization",
    "Expand product catalog"
  ]
}

GET/api/v1/commerce/strategic/benchmarking/industry-standards

Get industry benchmark standards for all supported sectors

Endpoints

Parameters:

Example Response:

{
  "industries": [
    "retail",
    "fashion",
    "electronics",
    "food_beverage"
  ],
  "benchmarks": {
    "retail": {
      "conversion_rate": 2.1,
      "average_order_value": 75
    }
  },
  "metrics": [
    "conversion_rate",
    "average_order_value",
    "cart_abandonment_rate"
  ]
}

GET/api/v1/commerce/strategic/intelligence/portfolio-summary

Get summary of commerce portfolio intelligence capabilities

Endpoints

Parameters:

Example Response:

{
  "total_models": 20,
  "active_models": 20,
  "average_accuracy": 0.932,
  "capabilities": [
    "Bundle Optimization",
    "Inventory Allocation",
    "Return Prediction",
    "Loyalty Optimization"
  ]
}

Rate Limits

API rate limits vary by plan:

Starter: 1,000 requests/hour
Professional: 10,000 requests/hour
Enterprise: Unlimited

Error Codes

Code	Description
400	Bad Request - Invalid parameters
401	Unauthorized - Invalid API key
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error

SDKs & Libraries

We provide official SDKs for popular programming languages:

Python

pip install brainpredict-commerce

Node.js

npm install @brainpredict/commerce

Java

mvn install brainpredict-commerce

PHP

composer require brainpredict/commerce