Auto-Refill - Unkey Docs

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#

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

Note

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 -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.

Note

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 -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/daytry {  const { meta, data } = await unkey.keys.createKey({    apiId,    credits: {      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/monthtry {  const { meta, data } = await unkey.keys.createKey({    apiId,    credits: {      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.createKey({ 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-monthtry {  const { meta, data } = await unkey.keys.updateKey({    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