Fund Usage After a Purchase

The operating model

When building usage-based billing systems, you may want to give new customers an initial credit balance (e.g., 10 free units) the moment they purchase a product. This comes in handy for:

Offering free trials with credits
Onboarding bonuses
Promotional credits for new signups or purchases

There are two ways to award initial meter credits in Ruba:

Meter Credits Benefit (Recommended) - Automatically grant credits when a customer purchases a product
Webhook + Events API - Programmatically grant credits for advanced use cases

Which Method Should I Use?

Feature	Meter Credits Benefit	Webhook + Events API
Setup Complexity	✅ Simple - No code required	⚙️ Advanced - Requires coding
Automatic Credits	✅ Yes	❌ No - Manual implementation
Custom Logic	❌ No	✅ Yes - Full control
One-time Products	✅ Credits granted at purchase	✅ Credits granted at purchase
Recurring Products	❌ No	✅ Can be credited every cycle (with code)
Best For	Most use cases	Complex crediting rules

Start with Method 1 (Meter Credits Benefit) unless you need custom logic or complex crediting rules. It’s simpler and requires no code.

Method 1: Using Meter Credits Benefit (Recommended)

The simplest route to award initial credits is to lean on the built-in Meter Credits benefit. It grants credits (once) to customers automatically when they purchase a product.

Step 1: Create a Meter with Sum Aggregation

First, create a meter to track your customers’ usage.

Step 2: Create a Meter Credits Benefit

Now create a Meter Credits benefit that grants the initial credits.

Step 3: Create a Product with the Benefit

Create a product and attach the Meter Credits benefit to it.

Create a product

Open Products → New Product in the dashboard.

Configure the product

Set a name and description
Choose your product type (Recurring)
Set the price (can be $0 for free signup, or any amount)
Click “Add Additional Price”
- Attach your meter to the product and set the per unit cost

Add the Meter Credits benefit

Scroll to the Automated Benefits section and toggle ON the Meter Credits benefit you created.

Save the product

Click Create Product to save.

That’s it! Now when a customer purchases this product, they automatically get the specified amount of meter credits.

Method 2: Using Webhooks + Events API (Advanced)

For trickier scenarios where you need custom logic or want to grant credits outside the purchase flow, lean on webhooks and the Events API.

When to Reach for This Method

You need custom logic to determine credit amounts
You want to grant credits based on external events
You need to grant credits to existing customers programmatically
You want to implement complex crediting rules

System flow

This approach boils down to:

Creating a product with a meter attached (using sum aggregation)
Setting up webhooks to listen for purchases
When a purchase is made, ingesting a negative event value to grant credits

Why negative values?When you ingest an event with a negative value (e.g., -10) into a meter using Sum aggregation, it effectively grants the customer 10 units of credit, lowering their usage meter balance.

Before you build

A Ruba account with an organization
A meter created with Sum aggregation
A product with the meter attached
Webhooks enabled
A Ruba access token for API calls

Step 1: Create a Meter

First, create a meter to track your customers’ usage.

Navigate to Meters

Open Products → Meters in the dashboard.

Create a new meter

Click Create Meter and configure:

Name: Give your meter a descriptive name (e.g., “API Calls” or “Storage Usage”)
Filter: Add filters to match your usage events (e.g., name equals “api_usage”)
Aggregation: Select Sum and enter the property to sum (e.g., units)

The meter must use Sum aggregation for this approach to work.

Save the meter

Save your meter and note the meter name, you’ll need this when ingesting events.

Learn more about creating meters.

Step 2. Create a Product

Follow the same steps as Method 1 to create your product (you don’t need to create or attach the Meter Credits benefit for this approach).

Step 3: Set Up Webhooks

Configure webhooks to get notified when users make purchases.

Add webhook endpoint

Follow our Configure Webhooks guide to create a new webhook endpoint.

Subscribe to order.paid event

When configuring your webhook, make sure to subscribe to the order.paid event. This event fires when a customer successfully completes a purchase.

Save webhook secret

Store your webhook secret securely in your environment variables.

Terminal

RUBA_ACCESS_TOKEN="ruba_pat_..."
RUBA_WEBHOOK_SECRET="whsec_..."
PRODUCT_ID="prod_..." # The product ID to grant credits for

Step 4: Implement the Webhook Handler

Build a webhook handler that listens for order.paid events and grants initial credits by ingesting negative event values.

Next.js Example

app/api/webhook/ruba/route.ts

import { Ruba } from '@getruba/sdk'
import { validateEvent } from '@getruba/sdk/webhooks'

const ruba = new Ruba({
  accessToken: process.env.RUBA_ACCESS_TOKEN,
  server: 'sandbox',
})

export async function POST(request: Request) {
  const body = await request.text()
  const event = validateEvent(
    body,
    Object.fromEntries(request.headers),
    process.env.RUBA_WEBHOOK_SECRET!,
  )

  if (event.type !== 'order.paid') return new Response(null, { status: 204 })

  const order = event.data as { product_id: string; customer_id: string }
  if (order.product_id !== process.env.PRODUCT_ID) {
    return new Response(null, { status: 204 })
  }

  const { error } = await ruba.POST('/v1/events/ingest', {
    body: {
      events: [{
        name: 'meter-name',
        customer_id: order.customer_id,
        metadata: { units: -10, reason: 'initial_signup_bonus' },
      }],
    },
  })

  if (error) return new Response('Unable to grant credits', { status: 500 })
  return new Response(null, { status: 204 })
}

Step 5: Test Your Integration

Verify that credits are properly granted when a customer makes a purchase.

Use the sandbox environment

Test your integration in Ruba’s sandbox environment to avoid disturbing production data.

Make a test purchase

Create a checkout session and complete a test purchase.

Verify webhook receipt

Check your server logs to confirm the order.paid webhook was received.

Check customer balance

Use the Customer Meters API to confirm the credits were applied:

const { data } = await ruba.GET('/v1/customer-meters/', {
  params: { query: { customer_id: 'cus_...' } },
})

console.log(data?.items[0]?.balance)

Important Considerations for the Webhook Method

Negative Balance vs. Positive Usage

When using negative events to grant credits:

A negative balance (e.g., -10) means the customer has 10 credits available
As the customer uses your service, positive events reduce this negative balance
When the balance reaches 0, the customer has used all their credits
Positive balances indicate usage beyond the granted credits

Example Flow

// Initial state: Customer has 0 balance
// You grant 10 credits: balance = -10

// Customer uses 3 units: balance = -7 (7 credits remaining)
// Customer uses 5 more units: balance = -2 (2 credits remaining)
// Customer uses 3 more units: balance = 1 (1 unit of overage, if metered pricing is enabled)

Preventing Double Credits

To avoid granting credits multiple times, consider:

Check order status - Only grant credits for new orders
Use idempotency - Track which orders you’ve already processed
Database records - Store a record of credit grants

// Example with idempotency check
const hasGrantedCredits = await checkIfAlreadyGranted(order.id);

if (!hasGrantedCredits) {
  await ruba.POST('/v1/events/ingest', {
    body: {
      events: [{
        name: 'meter-name',
        customer_id: order.data.customer_id,
        metadata: { units: -10 },
      }],
    },
  })

  await recordCreditGrant(order.id)
}

Launch Path

Shape the Offer

Run the Revenue Model

Deliver Customer Access

Build the Integration

Operate the Business

Implementation Playbooks

Fund Usage After a Purchase

The operating model

Which Method Should I Use?

Method 1: Using Meter Credits Benefit (Recommended)

Step 1: Create a Meter with Sum Aggregation

Step 2: Create a Meter Credits Benefit

Step 3: Create a Product with the Benefit

Method 2: Using Webhooks + Events API (Advanced)

When to Reach for This Method

System flow

Before you build

Step 1: Create a Meter

Step 2. Create a Product

Step 3: Set Up Webhooks

Step 4: Implement the Webhook Handler

Next.js Example

Step 5: Test Your Integration

Important Considerations for the Webhook Method

Negative Balance vs. Positive Usage

Example Flow

Preventing Double Credits

​The operating model

​Which Method Should I Use?

​Method 1: Using Meter Credits Benefit (Recommended)

​Step 1: Create a Meter with Sum Aggregation

​Step 2: Create a Meter Credits Benefit

​Step 3: Create a Product with the Benefit

​Method 2: Using Webhooks + Events API (Advanced)

​When to Reach for This Method

​System flow

​Before you build

​Step 1: Create a Meter

​Step 2. Create a Product

​Step 3: Set Up Webhooks

​Step 4: Implement the Webhook Handler

​Next.js Example

​Step 5: Test Your Integration

​Important Considerations for the Webhook Method

​Negative Balance vs. Positive Usage

​Example Flow

​Preventing Double Credits

The operating model

Which Method Should I Use?

Method 1: Using Meter Credits Benefit (Recommended)

Step 1: Create a Meter with Sum Aggregation

Step 2: Create a Meter Credits Benefit

Step 3: Create a Product with the Benefit

Method 2: Using Webhooks + Events API (Advanced)

When to Reach for This Method

System flow

Before you build

Step 1: Create a Meter

Step 2. Create a Product

Step 3: Set Up Webhooks

Step 4: Implement the Webhook Handler

Next.js Example

Step 5: Test Your Integration

Important Considerations for the Webhook Method

Negative Balance vs. Positive Usage

Example Flow

Preventing Double Credits