Skip to main content
This guide walks you through submitting a shelf photo, waiting for results, and reading the structured product data. You will need a Shelfforce account and an API key.

​
Prerequisites

  • A Shelfforce account (sign up here)
  • An API key with write permissions

​
How the analysis flow works

Shelf analysis is asynchronous. When you submit an image, Shelfforce queues it for processing and immediately returns an analysis ID. You then retrieve the results once processing completes. 
1. POST /analyses        →  You get back an analysis ID (status: "processing")
2. Analysis runs         →  Shelfforce's vision pipeline processes the image (10-30 seconds)
3. GET /analyses/:id     →  You retrieve the completed results with all detected products
There are two ways to know when results are ready:
MethodBest forHow it works
PollingQuick testing, scriptsLoop GET /analyses/:id every 3-5 seconds until status is completed
WebhooksProduction systemsRegister a URL and Shelfforce POSTs the result to you when ready
This quickstart uses polling. For webhooks, see the Webhooks guide.
1

Get your API key

Navigate to Settings > API Keys in the Shelfforce dashboard. Click Create API Key, give it a name, and select the write role.Copy the key immediately — it is only shown once.Your key will look like this:
sf_live_a1b2c3d4e5f6...
Store your API key securely. Never commit it to source control or expose it in client-side code.
2

Submit an image for analysis

Send a POST request to the analyses endpoint with the URL of a shelf image. The response comes back immediately with status: "processing" — the analysis runs in the background.
curl -X POST https://shelfforce.ai/api/v1/analyses \
  -H "Authorization: Bearer sf_live_a1b2c3d4..." \
  -H "Content-Type: application/json" \
  -d '{
    "imageUrl": "https://example.com/shelf.jpg"
  }'
The response includes an analysis ID and an initial status of processing:
{
  "data": {
    "id": "an_g7h8j9k0",
    "status": "processing",
    "createdAt": "2026-02-23T10:30:00Z"
  }
}
One credit is consumed per analysis. See Credits for details.
3

Poll for results

Analysis typically completes in 10-30 seconds depending on image complexity. Poll the analysis endpoint until the status changes to completed:
# Poll every 3 seconds until completed
while true; do
  RESULT=$(curl -s https://shelfforce.ai/api/v1/analyses/an_g7h8j9k0 \
    -H "Authorization: Bearer sf_live_a1b2c3d4...")

  STATUS=$(echo "$RESULT" | jq -r '.data.status')
  echo "Status: $STATUS"

  if [ "$STATUS" = "completed" ] || [ "$STATUS" = "failed" ]; then
    echo "$RESULT" | jq .
    break
  fi

  sleep 3
done
For production use, set up webhooks to receive a notification when analysis completes instead of polling. Webhooks are more efficient and eliminate wasted requests.
4

View detected products

Once the status is completed, the response includes a products array with every detected item:
{
  "data": {
    "id": "an_g7h8j9k0",
    "status": "completed",
    "totalRuns": 1,
    "completedRuns": 1,
    "failedRuns": 0,
    "productCount": 12,
    "createdAt": "2026-02-23T10:30:00Z",
    "completedAt": "2026-02-23T10:30:18Z",
    "products": [
      {
        "id": "prd_k1l2m3",
        "brand": "Coca-Cola",
        "description": "Coca-Cola Original 330ml Can",
        "category": "Beverages",
        "subcategory": "Carbonated Soft Drinks",
        "units": 4,
        "price": 1.49,
        "currency": "USD",
        "onSale": false,
        "confidence": 0.95,
        "shelfPosition": "eye-level",
        "fixtureType": "shelf"
      },
      {
        "id": "prd_n4o5p6",
        "brand": "Pepsi",
        "description": "Pepsi Original 330ml Can",
        "category": "Beverages",
        "subcategory": "Carbonated Soft Drinks",
        "units": 3,
        "price": 1.29,
        "discountedPrice": 1.19,
        "currency": "USD",
        "onSale": true,
        "confidence": 0.92,
        "shelfPosition": "eye-level",
        "fixtureType": "shelf"
      }
    ]
  }
}
Each product includes:
FieldDescription
brandDetected brand name
descriptionFull product description as seen on shelf
unitsNumber of visible facings
price / discountedPriceDetected shelf price and sale price (if applicable)
currencyISO 4217 currency code
onSaleWhether the product appears to be on promotion
confidenceDetection confidence score (0.0 to 1.0)
shelfPositionVertical position: top, eye-level, middle, bottom
fixtureTypeWhere it was found: shelf, fridge, floor-display, other
5

Next steps

You have successfully analyzed your first shelf image. Here is where to go next:

Shelf Analysis Guide

Deep dive into the analysis pipeline and all available fields.

Batch Analysis

Process up to 20 images in a single request.

Webhooks

Get notified when analyses complete instead of polling.

Field Operations

Create tasks and manage stores for field team workflows.