---
title: "useCredits"
description: "useCredits, auto-imported in the app: its options, return value and types."
canonical_url: "https://nuxt-backend.dev/docs/reference/api/use-credits"
---
# useCredits

## Interfaces

### CreditCycle

Defined in: [src/runtime/vue/composables/use-credits.ts](https://github.com/qruto/nuxt-backend/blob/main/src/runtime/vue/composables/use-credits.ts)

The billing period a meter's credited units belong to.

#### Properties

<table>
<thead>
  <tr>
    <th>
      Property
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Description
    </th>
    
    <th>
      Defined in
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <a id="start">
        
      </a>
      
       <code>
        start?
      </code>
    </td>
    
    <td>
      <code>
        Date
      </code>
    </td>
    
    <td>
      Start of the current cycle, when the provider reports one.
    </td>
    
    <td>
      <a href="https://github.com/qruto/nuxt-backend/blob/main/src/runtime/vue/composables/use-credits.ts" rel="nofollow">
        src/runtime/vue/composables/use-credits.ts
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <a id="end">
        
      </a>
      
       <code>
        end?
      </code>
    </td>
    
    <td>
      <code>
        Date
      </code>
    </td>
    
    <td>
      End of the current cycle — when unspent credits expire, if they do.
    </td>
    
    <td>
      <a href="https://github.com/qruto/nuxt-backend/blob/main/src/runtime/vue/composables/use-credits.ts" rel="nofollow">
        src/runtime/vue/composables/use-credits.ts
      </a>
    </td>
  </tr>
</tbody>
</table>

---

### UseCreditsOptions

Defined in: [src/runtime/vue/composables/use-credits.ts](https://github.com/qruto/nuxt-backend/blob/main/src/runtime/vue/composables/use-credits.ts)

#### Properties

<table>
<thead>
  <tr>
    <th>
      Property
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Description
    </th>
    
    <th>
      Defined in
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <a id="api">
        
      </a>
      
       <code>
        api?
      </code>
    </td>
    
    <td>
      <a href="https://nuxt-backend.dev/docs/reference/api/use-billing#billingapi">
        <code>
          BillingApi
        </code>
      </a>
    </td>
    
    <td>
      Override the injected <code>
        api.billing
      </code>
      
       namespace.
    </td>
    
    <td>
      <a href="https://github.com/qruto/nuxt-backend/blob/main/src/runtime/vue/composables/use-credits.ts" rel="nofollow">
        src/runtime/vue/composables/use-credits.ts
      </a>
    </td>
  </tr>
</tbody>
</table>

---

### UseCreditsReturn

Defined in: [src/runtime/vue/composables/use-credits.ts](https://github.com/qruto/nuxt-backend/blob/main/src/runtime/vue/composables/use-credits.ts)

#### Properties

<table>
<thead>
  <tr>
    <th>
      Property
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Description
    </th>
    
    <th>
      Defined in
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <a id="balance">
        
      </a>
      
       <code>
        balance
      </code>
    </td>
    
    <td>
      <code>
        ComputedRef
      </code>
      
      <<code>
        number
      </code>
      
       | <code>
        undefined
      </code>
      
      >
    </td>
    
    <td>
      Remaining prepaid credit balance for the meter, or <code>
        undefined
      </code>
      
       while loading.
    </td>
    
    <td>
      <a href="https://github.com/qruto/nuxt-backend/blob/main/src/runtime/vue/composables/use-credits.ts" rel="nofollow">
        src/runtime/vue/composables/use-credits.ts
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <a id="credited">
        
      </a>
      
       <code>
        credited
      </code>
    </td>
    
    <td>
      <code>
        ComputedRef
      </code>
      
      <<code>
        number
      </code>
      
       | <code>
        undefined
      </code>
      
      >
    </td>
    
    <td>
      Total credits granted for the meter (top-ups + plan grants), or <code>
        undefined
      </code>
      
       while loading.
    </td>
    
    <td>
      <a href="https://github.com/qruto/nuxt-backend/blob/main/src/runtime/vue/composables/use-credits.ts" rel="nofollow">
        src/runtime/vue/composables/use-credits.ts
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <a id="consumed">
        
      </a>
      
       <code>
        consumed
      </code>
    </td>
    
    <td>
      <code>
        ComputedRef
      </code>
      
      <<code>
        number
      </code>
      
       | <code>
        undefined
      </code>
      
      >
    </td>
    
    <td>
      Credits consumed for the meter, or <code>
        undefined
      </code>
      
       while loading.
    </td>
    
    <td>
      <a href="https://github.com/qruto/nuxt-backend/blob/main/src/runtime/vue/composables/use-credits.ts" rel="nofollow">
        src/runtime/vue/composables/use-credits.ts
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <a id="overage">
        
      </a>
      
       <code>
        overage
      </code>
    </td>
    
    <td>
      <code>
        ComputedRef
      </code>
      
      <<code>
        number
      </code>
      
       | <code>
        undefined
      </code>
      
      >
    </td>
    
    <td>
      Units consumed beyond what was credited — what a pay-as-you-go meter has run up this cycle and the provider will invoice. <code>
        0
      </code>
      
       for a meter that is still in prepaid credit; <code>
        undefined
      </code>
      
       while loading.
    </td>
    
    <td>
      <a href="https://github.com/qruto/nuxt-backend/blob/main/src/runtime/vue/composables/use-credits.ts" rel="nofollow">
        src/runtime/vue/composables/use-credits.ts
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <a id="cycle">
        
      </a>
      
       <code>
        cycle
      </code>
    </td>
    
    <td>
      <code>
        ComputedRef
      </code>
      
      <<a href="#creditcycle">
        <code>
          CreditCycle
        </code>
      </a>
      
       | <code>
        null
      </code>
      
       | <code>
        undefined
      </code>
      
      >
    </td>
    
    <td>
      The billing cycle these credits belong to: <code>
        undefined
      </code>
      
       while loading, <code>
        null
      </code>
      
       for a meter with no cycle at all (credits bought as a one-time pack), otherwise the current period.
    </td>
    
    <td>
      <a href="https://github.com/qruto/nuxt-backend/blob/main/src/runtime/vue/composables/use-credits.ts" rel="nofollow">
        src/runtime/vue/composables/use-credits.ts
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <a id="expiresatcycleend">
        
      </a>
      
       <code>
        expiresAtCycleEnd
      </code>
    </td>
    
    <td>
      <code>
        ComputedRef
      </code>
      
      <<code>
        boolean
      </code>
      
       | <code>
        undefined
      </code>
      
      >
    </td>
    
    <td>
      Whether the remaining balance expires at <a href="#end">
        CreditCycle.end
      </a>
      
       — <code>
        true
      </code>
      
       only when the plan's credits are known not to roll over and a cycle end is known. <code>
        undefined
      </code>
      
       while loading; <code>
        false
      </code>
      
       when credits carry over (or the provider has not said).
    </td>
    
    <td>
      <a href="https://github.com/qruto/nuxt-backend/blob/main/src/runtime/vue/composables/use-credits.ts" rel="nofollow">
        src/runtime/vue/composables/use-credits.ts
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <a id="meterid">
        
      </a>
      
       <code>
        meterId
      </code>
    </td>
    
    <td>
      <code>
        ComputedRef
      </code>
      
      <<code>
        string
      </code>
      
       | <code>
        undefined
      </code>
      
      >
    </td>
    
    <td>
      The resolved meter id (the one read above) — pass it to your server-side spend.
    </td>
    
    <td>
      <a href="https://github.com/qruto/nuxt-backend/blob/main/src/runtime/vue/composables/use-credits.ts" rel="nofollow">
        src/runtime/vue/composables/use-credits.ts
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <a id="isloading">
        
      </a>
      
       <code>
        isLoading
      </code>
    </td>
    
    <td>
      <code>
        ComputedRef
      </code>
      
      <<code>
        boolean
      </code>
      
      >
    </td>
    
    <td>
      <code>
        true
      </code>
      
       until credit balances have loaded.
    </td>
    
    <td>
      <a href="https://github.com/qruto/nuxt-backend/blob/main/src/runtime/vue/composables/use-credits.ts" rel="nofollow">
        src/runtime/vue/composables/use-credits.ts
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <a id="topup">
        
      </a>
      
       <code>
        topUp
      </code>
    </td>
    
    <td>
      (<code>
        productIds
      </code>
      
      , <code>
        options?
      </code>
      
      ) => <code>
        Promise
      </code>
      
      <<code>
        string
      </code>
      
      >
    </td>
    
    <td>
      Buy a credit pack (a one-time product) via checkout — returns the URL.
    </td>
    
    <td>
      <a href="https://github.com/qruto/nuxt-backend/blob/main/src/runtime/vue/composables/use-credits.ts" rel="nofollow">
        src/runtime/vue/composables/use-credits.ts
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <a id="gift">
        
      </a>
      
       <code>
        gift
      </code>
    </td>
    
    <td>
      (<code>
        pack
      </code>
      
      , <code>
        options
      </code>
      
      ) => <code>
        Promise
      </code>
      
      <<code>
        string
      </code>
      
      >
    </td>
    
    <td>
      Buy a credit pack, by its catalog key (<code>
        credits500
      </code>
      
      ), as a gift for someone else (by email). Opens checkout.
    </td>
    
    <td>
      <a href="https://github.com/qruto/nuxt-backend/blob/main/src/runtime/vue/composables/use-credits.ts" rel="nofollow">
        src/runtime/vue/composables/use-credits.ts
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <a id="refresh">
        
      </a>
      
       <code>
        refresh
      </code>
    </td>
    
    <td>
      () => <code>
        Promise
      </code>
      
      <<code>
        void
      </code>
      
      >
    </td>
    
    <td>
      Refresh the cached balance from the provider (e.g. right after a top-up completes).
    </td>
    
    <td>
      <a href="https://github.com/qruto/nuxt-backend/blob/main/src/runtime/vue/composables/use-credits.ts" rel="nofollow">
        src/runtime/vue/composables/use-credits.ts
      </a>
    </td>
  </tr>
</tbody>
</table>

## Functions

### useCredits()

```ts
function useCredits(meterId?, options?): UseCreditsReturn;
```

Defined in: [src/runtime/vue/composables/use-credits.ts](https://github.com/qruto/nuxt-backend/blob/main/src/runtime/vue/composables/use-credits.ts)

Reactive prepaid-credit balance for the current user, plus a `topUp()` checkout
and a `refresh()` re-sync. Credits are the provider's native model: a credit pack is a
one-time product whose Credits benefit tops up a meter balance, drawn down by
server-side consumption (`setupBilling().spendCredits`). Reads the component's
webhook-synced cache via `getCredits`. Zero-arg via the auto-provided
`api.billing` namespace; pass `{ api }` to override.

Alongside the balance it exposes what a credits UI actually needs to say:
the current `cycle`, whether the remainder `expiresAtCycleEnd`, and the
`overage` a pay-as-you-go meter has run up.

#### Parameters

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        meterId?
      </code>
    </td>
    
    <td>
      <code>
        MaybeRefOrGetter
      </code>
      
      <<code>
        string
      </code>
      
      >
    </td>
    
    <td>
      Optional meter to read (reactive): a configured meter name (<code>
        'credits'
      </code>
      
      ) or a raw meter id; defaults to the user's first meter.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        options?
      </code>
    </td>
    
    <td>
      <a href="#usecreditsoptions">
        <code>
          UseCreditsOptions
        </code>
      </a>
    </td>
    
    <td>
      -
    </td>
  </tr>
</tbody>
</table>

#### Returns

[`UseCreditsReturn`](#usecreditsreturn)

#### Example

```vue
<script setup lang="ts">
const credits = useCredits()
</script>
<template>
  <p>{{ credits.balance.value ?? '—' }} credits</p>
  <button @click="credits.topUp(creditPackId)">Buy 100 credits</button>
</template>
```


## Sitemap

See the full [sitemap](https://nuxt-backend.dev/sitemap.md) for all pages.