> ## Documentation Index
> Fetch the complete documentation index at: https://unkey.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Auto-Refill
> Automatically restore usage credits for API keys on a daily or monthly schedule. Configure auto-refill amounts and intervals in Unkey.
Auto-refill works with [usage limits](/platform/apis/features/remaining) 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
"Pro plan: 50,000 requests/month", credits reset on the 1st of each month.
Free tier users get 100 requests per day, resets at midnight UTC.
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:
```bash cURL theme={"theme":"kanagawa-wave"}
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
}
}
}'
```
```typescript TypeScript theme={"theme":"kanagawa-wave"}
try {
const { meta, data } = await unkey.keys.createKey({
apiId: "api_...",
credits: {
remaining: 10000,
refill: {
interval: "monthly",
amount: 10000,
},
},
});
console.log(data.keyId);
} catch (error) {
console.error(error);
return Response.json({ error: "Internal error" }, { status: 500 });
}
```
### Monthly refill on a specific day
If your billing cycle is mid-month, set `refillDay`:
```json theme={"theme":"kanagawa-wave"}
{
"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:
```bash cURL theme={"theme":"kanagawa-wave"}
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
}
}
}'
```
```typescript TypeScript theme={"theme":"kanagawa-wave"}
try {
const { meta, data } = await unkey.keys.createKey({
apiId: "api_...",
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 });
}
```
## Update refill settings
Change an existing key's refill configuration:
```bash theme={"theme":"kanagawa-wave"}
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:
```bash theme={"theme":"kanagawa-wave"}
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
```typescript theme={"theme":"kanagawa-wave"}
// Free tier: 100/day
try {
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/month
try {
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:
```typescript theme={"theme":"kanagawa-wave"}
// User upgraded from Free to Pro mid-month
try {
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
Learn more about credits and custom costs
Track usage patterns per key