ShopIQ API Documentation

GET /api/v2/third-party/isAccountCreated?email=user@example.com
Host: api-development.shopiq.dev
x-api-key: your-api-key-here

GET /api/v2/third-party/isAccountCreated?email=user@example.com
Host: api-development.shopiq.dev
Authorization: Bearer your-api-key-here

POST /partner/v1/image/create
Host: api.shopiq.app
X-API-Key: sq_live_your-key-here
Content-Type: application/json

// 401 — No API key provided
{
  "success": false,
  "message": "API key required. Provide via X-API-Key header."
}

// 401 — Invalid API key
{
  "success": false,
  "message": "Invalid or revoked API key"
}

// 403 — Partner deactivated
{
  "success": false,
  "message": "Partner account is inactive"
}

// 401 — Expired API key
{
  "success": false,
  "message": "API key has expired"
}

// 403 — IP not whitelisted
{
  "success": false,
  "message": "Request IP not in API key whitelist"
}

// 429 — Too Many Requests
{
  "success": false,
  "message": "Rate limit exceeded: 60 requests per minute"
}

// 429 — Daily limit exceeded
{
  "success": false,
  "message": "Daily rate limit exceeded: 10000 requests per day"
}

{
  "success": false,
  "message": "Human-readable error description.",
  "timestamp": "2025-07-15T10:30:00.000Z"
}

{
  "email": "sarah@novaretail.com",
  "mobileNumber": {
    "value": "9876543210",
    "countryCode": 91
  },
  "firstName": "Sarah",
  "lastName": "Mitchell",
  "businessName": "Nova Retail",
  "typeOfBusiness": "Retail",
  "businessCategory": "Fashion & Clothing",
  "address": {
    "addLineOne": "42 Commerce Street",
    "city": "Mumbai",
    "state": "Maharashtra",
    "country": "India",
    "pincode": "400001"
  }
}

const crypto = require("crypto");

function verifyWebhook(body, signature, secret) {
  const expected = "sha256=" + crypto
    .createHmac("sha256", secret)
    .update(JSON.stringify(body))
    .digest("hex");
  return signature === expected;
}

// In your webhook handler:
app.post("/webhooks/shopiq", (req, res) => {
  const signature = req.headers["x-shopiq-signature"];
  const isValid = verifyWebhook(req.body, signature, "whsec_your_secret_here");

  if (!isValid) {
    return res.status(401).send("Invalid signature");
  }

  console.log("Event:", req.body.event);
  res.status(200).send("OK");
});

// website.building
{
  "event": "website.building",
  "accountId": "665a1f2e3b4c5d6e7f8a9b0c",
  "identifier": "nova-retail-abc123",
  "message": "AI is building your website...",
  "timestamp": "2025-07-15T10:30:00.000Z"
}

// website.created
{
  "event": "website.created",
  "accountId": "665a1f2e3b4c5d6e7f8a9b0c",
  "identifier": "nova-retail-abc123",
  "previewUrl": "https://nova-retail-abc123.dev.shopiq.app",
  "message": "Website created. Deploying to production...",
  "timestamp": "2025-07-15T10:32:00.000Z"
}

// deployment.success
{
  "event": "deployment.success",
  "accountId": "665a1f2e3b4c5d6e7f8a9b0c",
  "identifier": "nova-retail-abc123",
  "productionUrl": "https://nova-retail-abc123.shopiq.app",
  "previewUrl": "https://nova-retail-abc123.dev.shopiq.app",
  "message": "Website is live!",
  "timestamp": "2025-07-15T10:35:00.000Z"
}

// deployment.failed
{
  "event": "deployment.failed",
  "accountId": "665a1f2e3b4c5d6e7f8a9b0c",
  "identifier": "nova-retail-abc123",
  "error": "GitHub Actions deployment failed",
  "timestamp": "2025-07-15T10:35:00.000Z"
}

{
  "success": true,
  "message": "Success",
  "data": {
    "imageUrl": "https://...",
    "mode": "fast",
    "resolution": "1k",
    "pointsUsed": 8,
    "tier": "starter",
    "costPerOperation": 8,
    "remainingBalance": 4992,
    "processingTimeMs": 12500,
    "totalTimeMs": 13200
  },
  "timestamp": "2025-07-15T10:30:00.000Z"
}

11. Image Create

curl -X POST https://api-partners.shopiq.app/partner/v1/image/create \
  -H "Content-Type: application/json" \
  -H "X-API-Key: sq_live_your-key-here" \
  -d '{
    "prompt": "A premium leather handbag on a marble surface with soft studio lighting, luxury fashion photography",
    "aspectRatio": "1:1",
    "mode": "fast",
    "resolution": "1k"
  }'

curl -X POST https://api-partners.shopiq.app/partner/v1/image/create \
  -H "Content-Type: application/json" \
  -H "X-API-Key: sq_live_your-key-here" \
  -d '{
    "prompt": "minimalist sneaker product shot for an e-commerce store",
    "aspectRatio": "4:3",
    "mode": "thinking",
    "resolution": "2k"
  }'

{
  "success": true,
  "message": "Success",
  "data": {
    "imageUrl": "https://your-bucket.s3.ap-south-1.amazonaws.com/partners/abc123/generated/uuid.png",
    "mode": "fast",
    "resolution": "1k",
    "pointsUsed": 8,
    "tier": "starter",
    "costPerOperation": 8,
    "remainingBalance": 4992,
    "processingTimeMs": 11234,
    "totalTimeMs": 11890
  },
  "timestamp": "2025-07-15T10:30:00.000Z"
}

// 400 — Invalid prompt
{
  "success": false,
  "message": "Prompt is required and must be at least 3 characters"
}

// 400 — Prompt too long
{
  "success": false,
  "message": "Prompt must be less than 4000 characters"
}

// 400 — Invalid aspect ratio
{
  "success": false,
  "message": "Invalid aspect ratio. Supported: 1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3"
}

// 400 — Invalid mode
{
  "success": false,
  "message": "Invalid mode. Supported: fast, thinking"
}

// 400 — Invalid resolution
{
  "success": false,
  "message": "Invalid resolution. Supported: 1k, 2k, 4k"
}

// 402 — Insufficient points
{
  "success": false,
  "message": "Insufficient points. Required: 8 (starter tier, fast mode), Available: 3. Please top up your account."
}

// 422 — Safety filter blocked
{
  "success": false,
  "message": "Image generation was blocked by safety filters: [reason]"
}

// 503 — Service unavailable
{
  "success": false,
  "message": "Service temporarily unavailable due to high demand. Please retry in a few seconds."
}

// 500 — Generation failed
{
  "success": false,
  "message": "Image generation failed. Please try again."
}

• Points are automatically refunded if image generation fails after deduction.
• Request timeout is 2 minutes. Complex prompts in thinking mode may take 30–60 seconds.
• Generated images are stored permanently on S3 with public-read access and 1-year cache headers.
• If AI fails in thinking mode, the system automatically falls back to fast mode.

12. Image Enhance

curl -X POST https://api-partners.shopiq.app/partner/v1/image/enhance \
  -H "Content-Type: application/json" \
  -H "X-API-Key: sq_live_your-key-here" \
  -d '{
    "images": [
      "https://example.com/product-photo-raw.jpg"
    ],
    "userRequest": "Remove the background and place on a clean white surface with soft shadows. Make colors more vibrant.",
    "aspectRatio": "1:1",
    "mode": "fast",
    "resolution": "2k"
  }'

curl -X POST https://api-partners.shopiq.app/partner/v1/image/enhance \
  -H "Content-Type: application/json" \
  -H "X-API-Key: sq_live_your-key-here" \
  -d '{
    "images": [
      "https://example.com/product-front.jpg",
      "https://example.com/product-side.jpg"
    ],
    "userRequest": "Create a professional e-commerce product listing image",
    "aspectRatio": "4:3",
    "mode": "thinking",
    "resolution": "1k"
  }'

curl -X POST https://api-partners.shopiq.app/partner/v1/image/enhance \
  -H "Content-Type: application/json" \
  -H "X-API-Key: sq_live_your-key-here" \
  -d '{
    "images": [
      "https://example.com/low-quality-photo.jpg"
    ],
    "mode": "thinking"
  }'

{
  "success": true,
  "message": "Success",
  "data": {
    "imageUrls": [
      "https://your-bucket.s3.ap-south-1.amazonaws.com/partners/abc123/enhanced/uuid1.png",
      "https://your-bucket.s3.ap-south-1.amazonaws.com/partners/abc123/enhanced/uuid2.png"
    ],
    "mode": "thinking",
    "resolution": "1k",
    "pointsUsed": 15,
    "tier": "starter",
    "costPerOperation": 15,
    "remainingBalance": 4985,
    "processingTimeMs": 18500,
    "totalTimeMs": 19200
  },
  "timestamp": "2025-07-15T10:30:00.000Z"
}

// 400 — No images provided
{
  "success": false,
  "message": "At least one image URL is required in the 'images' array"
}

// 400 — Too many images
{
  "success": false,
  "message": "Maximum 4 images per request"
}

// 400 — Invalid URLs
{
  "success": false,
  "message": "All images must be valid HTTP/HTTPS URLs"
}

// 400 — User request too long
{
  "success": false,
  "message": "User request must be less than 2000 characters"
}

// 400 — Failed to download image
{
  "success": false,
  "message": "Failed to download image: [error details]"
}

// 402 — Insufficient points
{
  "success": false,
  "message": "Insufficient points. Required: 15 (starter tier, thinking mode), Available: 10. Please top up your account."
}

// 422 — Safety filter blocked
{
  "success": false,
  "message": "Enhancement blocked by safety filters: [reason]"
}

// 503 — Service unavailable
{
  "success": false,
  "message": "Service temporarily unavailable. Please retry shortly."
}

// 500 — Enhancement failed
{
  "success": false,
  "message": "Image enhancement failed. Please try again."
}

• Images are downloaded from the provided URLs. Ensure they are publicly accessible.
• Maximum image download size is 50MB per image.
• Supported input formats: JPEG, PNG, GIF, WebP.
• Output is always PNG format for maximum quality.
• Points are automatically refunded if enhancement fails after deduction.
• The number of output images may differ from input — the model may combine or produce additional variations.
• If AI fails in thinking mode, the system automatically falls back to fast mode.

13. Image Usage Stats

curl -X GET https://api-partners.shopiq.app/partner/v1/image/usage \
  -H "X-API-Key: sq_live_your-key-here"

{
  "success": true,
  "message": "Success",
  "data": {
    "last30Days": {
      "imageCreations": 142,
      "imageEnhancements": 87,
      "totalCalls": 229
    },
    "points": {
      "balance": 18750,
      "totalUsed": 6250,
      "monthlyUsage": {
        "month": "2025-07",
        "used": 3200
      }
    },
    "currentPricing": {
      "tier": "growth",
      "imageCreateFast": 7.25,
      "imageCreateThinking": 14,
      "imageEnhanceFast": 7.25,
      "imageEnhanceThinking": 14
    },
    "activeBuckets": [
      {
        "packageId": "pack_25000",
        "tier": "growth",
        "remainingPoints": 18750,
        "originalPoints": 25000,
        "purchasedAt": "2025-07-01T00:00:00.000Z"
      }
    ],
    "allTierPricing": {
      "starter": {
        "tier": "starter",
        "createFast": 8,
        "createThinking": 15,
        "enhanceFast": 8,
        "enhanceThinking": 15
      },
      "growth": {
        "tier": "growth",
        "createFast": 7.25,
        "createThinking": 14,
        "enhanceFast": 7.25,
        "enhanceThinking": 14
      },
      "scale": {
        "tier": "scale",
        "createFast": 6,
        "createThinking": 11,
        "enhanceFast": 6,
        "enhanceThinking": 11
      }
    },
    "supportedResolutions": ["1k", "2k", "4k"],
    "defaultResolution": "1k"
  },
  "timestamp": "2025-07-15T10:30:00.000Z"
}

• FIFO Bucket System: Points are deducted from the oldest active bucket first. The cost is determined by the tier of the bucket being deducted from.
• Multiple Buckets: You can have multiple active buckets from different tiers. If your oldest bucket runs out mid-operation, the remaining cost is deducted from the next bucket.
• Automatic Refunds: If an operation fails after points are deducted, the points are automatically refunded to your account.
• No Expiry: Purchased points do not expire. Use them at your own pace.

Scenario: You have a Growth bucket (25,000 points)

• Image Create (fast mode):  7.25 points per call
  → 25,000 ÷ 7.25 = ~3,448 images

• Image Create (thinking mode): 14 points per call
  → 25,000 ÷ 14 = ~1,785 images

• Image Enhance (fast mode): 7.25 points per call
  → 25,000 ÷ 7.25 = ~3,448 enhancements

• Image Enhance (thinking mode): 14 points per call
  → 25,000 ÷ 14 = ~1,785 enhancements

• No AI models are triggered — responses are instant.
• No points are deducted from your balance.
• Static placeholder images are returned instead of generated images.
• All validation rules still apply (prompt length, aspect ratio, etc.).
• Rate limiting still applies to prevent abuse.
• Responses include a testMode: true flag.

{
  "success": true,
  "message": "Success",
  "data": {
    "imageUrl": "https://placehold.co/1024x1024/1a1a2e/ffffff/png?text=ShopIQ+Test%0AImage+Create%0A1:1",
    "mode": "fast",
    "resolution": "1k",
    "pointsUsed": 0,
    "tier": "test",
    "costPerOperation": 0,
    "remainingBalance": null,
    "processingTimeMs": 5,
    "totalTimeMs": 5,
    "testMode": true,
    "message": "This is a test response. No AI model was triggered and no points were deducted. Use a live API key (sq_live_*) for actual image generation."
  },
  "timestamp": "2025-07-15T10:30:00.000Z"
}