Billing & Credits

Pharlo uses a prepaid credit system. You purchase credits in advance; each operation deducts from your balance. If your balance is too low, the request is rejected before it reaches any downstream platform.

Core principles

• Prepaid credits — operations are paid before they execute; no credit means no service
• Pre-debit with refund — credits are reserved when a job starts; returned in full if the operation fails (our fault or downstream platform error)
• Free operations stay free — authentication, OAuth, org management, health checks, and platform discovery never cost credits
• MCP surcharge — MCP tool invocations carry a 20% surcharge over equivalent REST API operations by default

Operation tiers

Exact credit costs are configured per tariff plan by your organization's admin and may differ from the defaults above. Use the balance endpoint to observe X-Credits-Used on live requests.

Checking your balance

curl https://pharlo.io/api/v1/billing/status \
  -H "Authorization: Bearer $DELIVERY_API_KEY"

Response:

{
  "balance": 1250,
  "plan": "growth",
  "monthlyCredits": 2000,
  "cycleResetsAt": "2026-05-01T00:00:00Z"
}

This endpoint is FREE — it does not consume credits and can be polled as often as needed.

Response headers on billable requests

Every billable API response includes headers so you can track consumption without an extra round-trip:

Example — inspecting headers in code:

# -i prints response headers
curl -i https://pharlo.io/api/v1/assignments \
  -H "Authorization: Bearer $DELIVERY_API_KEY"
 
# X-Credits-Used: 1
# X-Credits-Balance: 1249

Insufficient credits — 402 responses

When your balance is too low for an operation, the request is rejected immediately — no partial work is done and no credits are deducted:

HTTP/1.1 402 Payment Required
X-Credits-Required: 3
X-Credits-Balance: 1
 
{"error": "Insufficient credits", "required": 3, "balance": 1}

Handling 402 in code

STATUS=$(curl -s -o /tmp/response.json -w "%{http_code}" \
  -X POST https://pharlo.io/api/v1/assignments \
  -H "Authorization: Bearer $DELIVERY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contentItemId": "...", "connectionId": "..."}')
 
if [ "$STATUS" = "402" ]; then
  echo "Insufficient credits: $(cat /tmp/response.json)"
  exit 1
fi

Top up via the console or contact your organization admin. See Error Handling for the full list of API error codes.

Viewing transaction history

You can audit every credit movement — reservations, debits, refunds, and grants — via the transactions endpoint:

curl "https://pharlo.io/api/v1/billing/transactions?limit=20" \
  -H "Authorization: Bearer $DELIVERY_API_KEY"

Response:

{
  "items": [
    {
      "id": "019500ab-...",
      "type": "debit",
      "amount": -3,
      "balanceAfter": 1247,
      "description": "POST /api/v1/assignments",
      "createdAt": "2026-04-27T10:15:00Z"
    },
    {
      "id": "019500aa-...",
      "type": "reservation",
      "amount": -3,
      "balanceAfter": 1250,
      "description": "POST /api/v1/assignments",
      "createdAt": "2026-04-27T10:14:58Z"
    }
  ],
  "total": 840
}

Organization wallets

When you belong to an organization, the wallet is shared across all members. All members' operations draw from the same balance pool.

Organization admins can:

• View total org balance and per-user usage breakdown
• Set monthly credit limits per member (a per-member cap does not increase the shared pool)
• See REST vs MCP usage split

Per-member limits protect against runaway usage from a single integration — they do not grant additional credits beyond the org's total balance.

For channel and connection management within your org, see Connecting Channels.

Credit transaction types

The reservation → debit pair is normal: you will see both for every successful PLATFORM-tier operation. If an operation fails, only the refund appears (the reservation is cancelled, not debited).

Welcome credits

New accounts receive a one-time welcome credit pack when first subscribing to a plan. Unlike cycle_grant credits, welcome credits do not expire at the end of a billing cycle — they persist until used.

Welcome credits appear as welcome_grant entries in your transaction history and are included in your balance field from day one.

Per-client pricing overrides

For partner and enterprise accounts, individual operation prices can be overridden per API client without changing the underlying tariff plan. This allows different integrations to have different effective costs.

Price resolution order (highest priority first):

1. Per-client override
2. Plan pricing
3. Default plan fallback
4. Free (if unpriced — logged for admin review)

If you expect a specific cost per operation but observe a different X-Credits-Used value, your account likely has a per-client override applied. Contact your organization admin to review the configuration.