Buy usage balance

​

Insufficient usage balance response

• errorCode: "INSUFFICIENT_CREDITS" (legacy-compatible error code)
• meta.remainingUsageBalance
• upgradeOptions

{
    "results": [],
    "extraEntities": [],
    "referencesByResultId": {},
    "referencedEntities": [],
    "referencedTags": [],
    "meta": {
        "offset": 0,
        "limit": 0,
        "returnedCount": 0,
        "rerankApplied": false,
        "usageMicrosCharged": 0,
        "remainingUsageBalance": {
            "usageBalancePaygMicros": 0,
            "usageBalanceSubscriptionMicros": 0,
            "total": 0
        }
    },
    "error": "Insufficient usage balance.",
    "errorCode": "INSUFFICIENT_CREDITS",
    "upgradeOptions": {
        "environment": "production",
        "isProduction": true,
        "defaultPlanId": "unlimited-subscription-yearly",
        "plans": []
    }
}

​

Buy usage balance in the browser

• Open https://memex.garden/pricing
• Pick a plan and complete checkout in the browser

​

Buy usage balance from an agent

​

Step 1: fetch the current pricing catalog

curl -X POST "https://memex.garden/api/get-available-plans" \
  -H "Content-Type: application/json" \
  -d '{}'

​

Step 2: call checkout

curl -X POST "https://memex.garden/api/checkout" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_MEMEX_API_KEY" \
  -H "Idempotency-Key: UNIQUE_AGENT_PAYMENT_KEY" \
  -d '{
    "planId": "credit-pack-1000",
    "payment": {
      "provider": "stripe",
      "sharedPaymentToken": "spt_..."
    }
  }'

​

Agent operating rule

1. Show the user the available upgrade options if the response already contains upgradeOptions.
2. If upgradeOptions is missing or stale, call POST /get-available-plans.
3. Ask the human which plan they want.
4. If the selected plan is a one-time plan, obtain a Stripe Shared Payment Token from the agent payment harness.
5. Call POST /checkout with the user’s Memex bearer token and Shared Payment Token.
6. If the selected plan is a subscription plan, send the user to https://memex.garden/pricing.

​

Which requests currently consume usage balance

• Search responses expose charges as usageMicrosCharged and balances as remainingUsageBalance.
• Search currently reports usageMicrosCharged: 0.
• Saving content costs one credit per new library item. PDFs cost one credit per five pages. Notes and highlights are free.
• Transcription costs 20 credits per hour, and 70 credits per hour for premium transcription.
• A save that the balance cannot cover fails with errorCode: "SAVE_CONTENT_INSUFFICIENT_CREDITS".

​

Related docs

• Auth for checkout requests: Authentication
• Current plan and operation list: Available endpoints
• Response fields like upgradeOptions: Response shape