Auto-Refill

Automatically restore credits on a daily or monthly schedule

Auto-refill works with usage limits to automatically restore a key’s credits on a schedule. Perfect for subscription models where users get a fresh allocation each billing period.

When to use this

Monthly subscription quotas

“Pro plan: 50,000 requests/month” — credits reset on the 1st of each month.

Daily allowances

Free tier users get 100 requests per day, resets at midnight UTC.

Rolling credits

Automatically restore credits without manual intervention.

How it works

1. You create a key with credits.remaining and credits.refill configured
2. Unkey automatically refills the credits on your chosen schedule
3. Daily refills trigger at midnight UTC
4. Monthly refills trigger on a specific day of the month (default: 1st)

Refill replaces the current credit balance — it doesn’t add to it. A key with 50 remaining credits will have exactly 1000 after a refill of 1000, not 1050.

Create a key with auto-refill

Monthly refill (most common)

Key gets 10,000 credits that reset on the 1st of each month:

cURL

curl -X POST https://api.unkey.com/v2/keys.createKey \
  -H "Authorization: Bearer $UNKEY_ROOT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "apiId": "api_...",
    "credits": {
      "remaining": 10000,
      "refill": {
        "interval": "monthly",
        "amount": 10000
      }
    }
  }'

Monthly refill on a specific day

If your billing cycle is mid-month, set refillDay:

{
  "apiId": "api_...",
  "credits": {
    "remaining": 10000,
    "refill": {
      "interval": "monthly",
      "amount": 10000,
      "refillDay": 15
    }
  }
}

This refills on the 15th of each month.

For months with fewer days (e.g., February), refills on the last day of the month if refillDay exceeds the month’s length.

Daily refill

Key gets 100 credits that reset every night at midnight UTC:

cURL

curl -X POST https://api.unkey.com/v2/keys.createKey \
  -H "Authorization: Bearer $UNKEY_ROOT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "apiId": "api_...",
    "credits": {
      "remaining": 100,
      "refill": {
        "interval": "daily",
        "amount": 100
      }
    }
  }'

Update refill settings

Change an existing key’s refill configuration:

curl -X POST https://api.unkey.com/v2/keys.updateKey \
  -H "Authorization: Bearer $UNKEY_ROOT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "keyId": "key_...",
    "credits": {
      "remaining": 50000,
      "refill": {
        "interval": "monthly",
        "amount": 50000
      }
    }
  }'

Disable refill

To stop auto-refill but keep the current credits:

curl -X POST https://api.unkey.com/v2/keys.updateKey \
  -H "Authorization: Bearer $UNKEY_ROOT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "keyId": "key_...",
    "credits": {
      "refill": null
    }
  }'

Common patterns

Tiered subscription plans

// Free tier: 100/day
try {
  const { meta, data } = await unkey.keys.create({
    apiId,
    remaining: 100,
    refill: { interval: "daily", amount: 100 },
  });
  console.log(data.keyId);
} catch (error) {
  console.error(error);
  return Response.json({ error: "Internal error" }, { status: 500 });
}

// Pro tier: 50,000/month
try {
  const { meta, data } = await unkey.keys.create({
    apiId,
    remaining: 50000,
    refill: { interval: "monthly", amount: 50000 },
  });
  console.log(data.keyId);
} catch (error) {
  console.error(error);
  return Response.json({ error: "Internal error" }, { status: 500 });
}

// Enterprise: Unlimited (no credits object)
try {
  const { meta, data } = await unkey.keys.create({ apiId });
  console.log(data.keyId);
} catch (error) {
  console.error(error);
  return Response.json({ error: "Internal error" }, { status: 500 });
}

Upgrade a user’s plan

When a user upgrades, update their key:

// User upgraded from Free to Pro mid-month
try {
  const { meta, data } = await unkey.keys.update({
    keyId: "key_...",
    credits: {
      remaining: 50000,  // Give them the new allocation immediately
      refill: {
        interval: "monthly",
        amount: 50000,
      },
    },
  });
} catch (error) {
  console.error(error);
  return Response.json({ error: "Internal error" }, { status: 500 });
}

Refill vs manual credit management

Approach	Best for
Auto-refill	Subscription models with predictable, recurring quotas
Manual increment	Pay-as-you-go, top-ups, credit purchases

You can use both: set a base refill for the subscription, and manually increment when users purchase additional credits.

Next steps

Usage limits

Learn more about credits and custom costs

Analytics

Track usage patterns per key