Credits and usage

This guide explains how credits work in ACE, what consumes them, how to check your balance, and how to avoid running out partway through a batch.

Credits and test quota

There are two billing rails, and which one applies depends on the key you use.

• ace_live_ keys draw on your account's credit balance. When the balance is empty a metered request returns 402 INSUFFICIENT_CREDITS and does not run.
• ace_test_ keys are free and draw on a monthly quota instead, capped on both request count and units of work. When it is exhausted, requests return 402 TEST_QUOTA_EXCEEDED until the month rolls over.

Use a test key while you are building, and switch to a live key for production.

What uses credits

Work is metered in units. One unit is one product for one content type.

So ten products with ["product-description", "meta-tags", "jsonld-schema"] costs thirty units. The utilities, health, job tracking, and reading your own usage are all free.

The same accounting applies to the MCP tools: a tool marked as using credits is metered exactly like the endpoint behind it.

Check your balance

In the dashboard: sign in at https://ace.authoritas.com and open Settings, Developer console, Usage.

Via API:

curl https://ace.authoritas.com/api/v1/usage \
  -H "Authorization: Bearer $ACE_API_KEY"

{
  "data": {
    "env": "live",
    "credits": { "balance": 4820, "limit": null, "periodStart": "...", "periodEnd": "..." },
    "rateLimit": { "limitPerMinute": 120 },
    "jobs": { "total": 37 }
    // test keys also get: "testQuota": { requestsUsed, requestCap, unitsUsed, unitCap }
  }
}

Via CLI: ace usage. See ACE CLI.

From an assistant: the get_usage MCP tool returns the same snapshot.

Add credits

Add credits in the ACE dashboard under Settings. If you do not see the option, your organisation may manage billing centrally, so ask your admin.

Shopify-installed merchants

If you installed ACE from the Shopify App Store, your AI usage is billed directly on your Shopify invoice, not through the ACE dashboard. This is required by Shopify policy 1.2.1 (no off-platform billing).

The plan:

• 1,000 free credits per month, included with the app.
• $0.01 per credit after the free tier.
• Charges are capped at $500 per 30-day billing cycle. You will never exceed that without explicitly approving a higher cap.
• 1 credit is roughly one AI enrichment field (title, description, SEO meta). A full product enrichment is typically 5 to 10 credits depending on which fields you request.

Shopify shows the plan approval screen automatically on first install (Managed Pricing), and you are charged nothing until you pass the free tier. Review remaining free credits and the current cycle under Apps, Agentic Commerce Engine, Billing. Plan changes happen entirely in the Shopify admin; the app reads subscription state but never creates, modifies, or cancels charges.

On a Shopify-billed project, a request made before the plan is approved returns 402 SUBSCRIPTION_REQUIRED rather than drawing on an ACE balance. Uninstalling cancels the subscription. Balances do not carry between Shopify and the standalone dashboard; they are independent rails.

Avoiding 402

1. Check first. Call GET /api/v1/usage before a large run.
2. Estimate. Units are products × content types. Multiply before you send.
3. Use jobs. Large requests return 202 with a job id, so a long run does not sit on an open connection. Credits are consumed as the job progresses.
4. Split or top up. If you hit 402, add credits or send smaller batches.
5. Send an idempotency key. Retrying a request with the same Idempotency-Key resumes the original job rather than paying for a second one.

Summary

• Live keys spend credits; test keys spend a free monthly quota.
• Metered work is products × content types. Utilities, health, and job reads are free.
• Check with GET /api/v1/usage, ace usage, or the dashboard.
• Shopify-installed merchants bill through Shopify, not the ACE balance.

See the API Reference and Contextual Enrichment Engine for endpoint detail.