> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shelfforce.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Credits

> Understand how Shelfforce credits work, what costs credits, and how to manage your balance.

Shelfforce uses a credit-based system for image analysis. **1 credit = 1 image = \$0.10.** All other API operations — reading data, creating tasks, managing stores — are free.

## How credits work

| Operation                                     | Cost                                  |
| --------------------------------------------- | ------------------------------------- |
| Single analysis `POST /analyses`              | **1 credit (\$0.10)**                 |
| Batch analysis `POST /analyses/batch`         | **1 credit per image (\$0.10/image)** |
| All `GET` endpoints                           | Free                                  |
| All `POST`/`PATCH` (tasks, places, inventory) | Free                                  |
| Webhook delivery                              | Free                                  |

<Info>
  \*\*1 credit = 1 image analysis = $0.10.** One audit (a complete store visit) uses up to 20 images (20 credits = $2.00).
</Info>

<Note>
  Credits are consumed when an analysis is submitted, not when it completes. If an analysis fails due to an unreadable image, the credit is refunded automatically.
</Note>

## Plan credits

Every plan includes a monthly credit allocation that resets on your billing cycle date:

| Plan        | Monthly audits | Monthly images | Price    | Per image |
| ----------- | -------------- | -------------- | -------- | --------- |
| **Free**    | 5              | 100            | \$0/mo   | —         |
| **Starter** | 30             | 600            | \$49/mo  | \$0.082   |
| **Growth**  | 100            | 2,000          | \$149/mo | \$0.075   |
| **Pro**     | 400            | 8,000          | \$499/mo | \$0.062   |
| **Scale**   | 1,000          | 20,000         | \$899/mo | \$0.045   |

Annual billing is available on all paid plans — pay for 11 months, get 12.

Unused plan credits do not roll over to the next month.

## Pay-as-you-go audit packs

Purchase top-up audit packs from the [Settings page](https://shelfforce.ai/drive/settings?tab=usage):

| Pack       | Images | Price    | Per image |
| ---------- | ------ | -------- | --------- |
| 5 Audits   | 100    | \$12.50  | \$0.125   |
| 25 Audits  | 500    | \$49.75  | \$0.100   |
| 100 Audits | 2,000  | \$149.00 | \$0.075   |

PAYG credits **do not expire** and are consumed only after your monthly plan credits are used up.

## API overage pricing

If you exceed your plan credits, additional images are charged at \*\*$0.10 per image** ($2.00 per audit).

## Checking your balance

```bash theme={null}
curl https://shelfforce.ai/api/v1/usage \
  -H "Authorization: Bearer sf_live_a1b2c3d4..."
```

```json theme={null}
{
  "plan": "growth",
  "billingCycleStart": "2026-02-01T00:00:00Z",
  "billingCycleEnd": "2026-03-01T00:00:00Z",
  "planCredits": {
    "total": 2000,
    "used": 847,
    "remaining": 1153
  },
  "paygCredits": {
    "remaining": 500
  },
  "totalRemaining": 1653
}
```

## Insufficient credits

If you attempt an analysis without enough credits, the API returns a `402` error:

```json theme={null}
{
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "You have 0 credits remaining.",
    "details": { "required": 1, "available": 0 }
  }
}
```

For batch requests, the credit check is all-or-nothing — if you don't have enough credits for the full batch, the entire request is rejected.

<Tip>
  Set up a scheduled job to monitor your credit balance via `GET /api/v1/usage` and alert your team before credits run out.
</Tip>