Auto-Refill

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)

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
      }
    }
  }'

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:

{
  "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 -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
      }
    }
  }'

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:

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

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

Getting Started

Platform

Build & Deploy

Networking

Observability

CLI

Security

Keyspaces

AI Code Gen

Audit Logs

CLI

Errors

When to use this

Monthly subscription quotas

Daily allowances

Rolling credits

How it works

Create a key with auto-refill

Monthly refill (most common)

Monthly refill on a specific day

Daily refill

Update refill settings

Disable refill

Common patterns

Tiered subscription plans

Upgrade a user’s plan

Refill vs manual credit management

Next steps

Usage limits

Analytics

​When to use this

Monthly subscription quotas

Daily allowances

Rolling credits

​How it works

​Create a key with auto-refill

​Monthly refill (most common)

​Monthly refill on a specific day

​Daily refill

​Update refill settings

​Disable refill

​Common patterns

​Tiered subscription plans

​Upgrade a user’s plan

​Refill vs manual credit management

​Next steps

Usage limits

Analytics

When to use this

How it works

Create a key with auto-refill

Monthly refill (most common)

Monthly refill on a specific day

Daily refill

Update refill settings

Disable refill

Common patterns

Tiered subscription plans

Upgrade a user’s plan

Refill vs manual credit management

Next steps