Usage & Credits

MinuteShip can meter any feature, not just AI calls. Each feature chooses one of three billing modes, so the same site can mix a free converter, a subscription-only tool and a pay-per-use generator.

Billing modes

Mode	Best for	What users experience
unlimited	Free tools, ad-supported pages	Nothing is blocked or charged
daily-limit	Free tier with an upgrade path	A fixed number of uses per day, resetting at midnight UTC
credits	AI calls, pay-per-use tools	Each use spends credits from the user's balance

Features without a configured mode are unlimited by default, so adding a new tool never blocks users until you decide to meter it.

Configure a feature

Open src/config/usage.ts and add the feature to usagePolicies:

export const usagePolicies = {
  generateAiImage: { mode: 'credits', cost: 10 },
  'pdf.merge': { mode: 'daily-limit', perDay: 3 },
  'json.format': { mode: 'unlimited' },
};

Field	Meaning
mode	unlimited, daily-limit or credits
cost	Credits spent per call (credits mode)
perDay	Allowed calls per UTC day (daily-limit mode)

To meter a server function, add usageGuard('feature-key') to its middleware chain. Failed calls are refunded automatically, so users are not charged when a generation fails.

Set credits for plans and signups

Also in src/config/usage.ts:

export const walletConfig = {
  signupBonus: { enabled: true, amount: 50 },
  planCredits: { free: 0, pro: 1000, lifetime: 5000 },
};

• signupBonus — credits granted when an account is created. Set enabled: false to turn the bonus off.
• planCredits — monthly allowance for each plan id; it is granted once per billing period and resets at the start of the next one.

Give paid plans better limits

A plan can override a feature's policy, including switching its mode:

export const planPolicyOverrides = {
  pro: {
    'pdf.merge': { mode: 'daily-limit', perDay: 100 },
  },
  lifetime: {
    'pdf.merge': { mode: 'unlimited' },
  },
};

The plan is taken from the user's paid records: an active subscription first, then a lifetime purchase, otherwise free.

What users see

/settings/usage shows the credit balance (plan and purchased) and a history of metered calls. When a site only uses free or daily-limited features, the wallet cards are hidden and only usage is listed.

What admins can do

Page	Purpose
/admin/usage	Look up any user and review their balance and recent usage
/admin/credits	Add or remove credits manually, with a required note
/admin/orders	See what each customer bought and whether it was paid

Visitors who are not signed in

Free tools work without an account: anonymous visitors are tracked with a cookie, so daily limits apply per browser. That is enough to guide users toward signing up, but it is not an anti-abuse measure — add edge rate limiting if you need stronger protection.

Notes

• Credits purchased as one-time packs never expire; plan credits reset each period.
• Subscription allowances are applied the next time the balance is read, so they can appear a moment after a successful checkout.
• Refunds are handled in the payment provider's dashboard.