Credits & Usage
Credits are the unit of consumption in MultiCartAPI. Every item you scrape costs one credit, and your plan determines how many you receive each billing cycle.
What counts as one credit
Every billable operation deducts exactly 1 credit — regardless of how it was triggered:
| Trigger | Cost |
|---|---|
| Playground scrape (single ASIN/SKU) | 1 credit |
| Collection run — per item scraped | 1 credit |
| Category metering — per product enumerated | 1 credit |
One ASIN, one SKU, one product = one credit. Batch size does not change the per-item rate.
Where credits come from
- Signup grant
- Every new account receives 500 credits on registration (Starter plan quota). These are a one-time lifetime grant — they never auto-reset and are not re-granted if you cancel a paid plan and revert to Starter.
- Plan quota
- Paid plans (Basic through Pro) reset your credit pool to the plan's full scrape quota on each successful billing-cycle payment. The reset is triggered by PayPal's payment confirmation, not by a date.
- Upgrade carryover
- When you upgrade to a higher plan, any unused credits at the moment you switch are captured and added on top of the new plan's full quota after the first payment lands. You never lose credits you have already earned.
Downgrade carry-over too
When you downgrade to a lower plan, your existing credit balance carries into the new cycle unchanged — it is not reset to the lower quota. Only a same-plan renewal resets the counter.
Your credit balance — three fields
The platform tracks three numbers for your account at all times:
| Field | Meaning |
|---|---|
| `available_credits` | Total credits granted for your current cycle. |
| `used_credits` | Credits fully consumed by completed scrapes. |
| `frozen_credits` | Credits reserved for jobs that are currently in-flight but not yet finalised. |
Spendable balance
The credits you can actually spend right now are:
spendable = available_credits − (used_credits + frozen_credits)
A database constraint enforces available_credits ≥ used_credits + frozen_credits at all times, so the spendable number is always ≥ 0.
Why frozen credits exist
When a scrape job starts, the platform reserves the credit before the work begins — this is frozen_credits. The reservation prevents two concurrent jobs from both believing they have the same credit available. Once the job completes, the frozen amount moves into used_credits and is released from the frozen pool.
If a job fails or is cancelled before finishing, the frozen credit is released back to your spendable balance automatically.
The credit gate — try_consume
Before any scrape starts, the platform runs a single atomic check-and-deduct operation (try_consume). It executes a conditional database update:
- If
spendable ≥ 1— the credit is frozen and the job proceeds. - If
spendable < 1— the job is rejected immediately and no work is performed. You are not charged for a rejected request.
This gate eliminates race conditions under parallel workloads — with concurrent workers running at once, every reservation is serialised at the database level.
Out of credits stops jobs immediately
When your spendable balance hits zero, new scrape requests are refused at the gate — no partial batches, no silent failures. Top up by upgrading your plan or waiting for your next billing cycle to reset your quota.
Viewing your usage
The Usage page shows your live credit balance plus a 30-day rolling breakdown of how credits were spent across your collections.
Open Usage dashboard
Credit lifecycle at a glance
Signup → 500 credits granted (one-time, Starter plan)
Pay for plan → available_credits reset to plan quota, used_credits reset to 0
frozen_credits are NOT reset (protects in-flight jobs)
Scrape starts → frozen_credits += 1 (try_consume gate)
Scrape ends → frozen_credits -= 1, used_credits += 1
Upgrade → carryover balance preserved; added on top after first payment
Downgrade → balance carries forward unchanged into new cycle
Refund → grant is clawed back; floor is max(used + frozen, available − grant)