> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getruba.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Grant Usage Before a Purchase
> Discover how to grant meter credits to customers before they make any purchase using the Ruba API.
export const RubaSocials = () => {
if (typeof document === "undefined") {
return null;
}
const inject = () => {
const footer = document.getElementById("footer");
if (!footer || document.getElementById("ruba-socials")) {
return false;
}
const isDark = document.querySelector("html.dark") || document.querySelector('html[class*="dark"]');
const lineColor = isDark ? "#383838" : "#e8e8ed";
const iconColor = isDark ? "#8e8e93" : "#86868b";
const markColor = isDark ? "#ffffff" : "#08080c";
const hoverColor = "#0071e3";
const div = document.createElement("div");
div.id = "ruba-socials";
div.style.cssText = `display:flex;align-items:center;gap:20px;padding-top:20px;margin-top:20px;border-top:1px solid ${lineColor};width:100%`;
const logo = `Ruba`;
const spacer = ``;
const ig = ``;
const li = ``;
const x = ``;
const github = ``;
div.innerHTML = logo + spacer + ig + li + x + github;
footer.appendChild(div);
return true;
};
if (!document.documentElement.dataset.rubaSocialsObserver) {
document.documentElement.dataset.rubaSocialsObserver = "true";
const observer = new MutationObserver(() => {
if (!document.getElementById("ruba-socials")) {
inject();
}
});
observer.observe(document.body, {
childList: true,
subtree: true
});
}
setTimeout(() => {
if (!inject()) {
const interval = setInterval(() => {
if (inject()) {
clearInterval(interval);
}
}, 500);
setTimeout(() => clearInterval(interval), 10000);
}
}, 300);
return null;
};
## The operating model
You may want to grant usage credits to customers even before they make a purchase. This is handy for:
* **Free trial credits** - Give new signups free credits to try your service
* **Promotional campaigns** - Grant credits as part of marketing initiatives
* **Testing and demos** - Provide credits for product demonstrations
This guide walks you through granting credits to customers who don't yet have an active subscription or purchase.
## System flow
To grant credits before a purchase, you need to:
1. Create a customer in Ruba (if they don't exist)
2. Create a meter with **Sum** aggregation to track usage
3. Ingest an event with a **negative 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 grants the customer credits. A negative balance means available credits, which get reduced as they use your service.
## Step 1: Create a Meter
First, create a meter to track your customers' usage.
Open [**Products → Meters**](https://getruba.com/to/dashboard/products/meters) in the dashboard.
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 your meter and note the meter name, you'll need this when ingesting events.
Learn more about [creating meters](/features/usage-based-billing/meters).
## Step 2: Create a Customer
If your customer doesn't already exist in Ruba, create them first.
### Option A: Create via Dashboard
Open [**Customers**](https://getruba.com/to/dashboard/customers) in the dashboard.
Click **Add Customer** and fill in:
* **Email**: Customer's email address (required)
* **Name**: Customer's full name (optional)
* **External ID**: Your internal user ID for easy reference (optional but recommended)
Click **Save** and note the Customer ID.
### Option B: Create via API
Use the Ruba SDK or API to create a customer programmatically:
```typescript icon="square-js" title="create-customer.ts" theme={"system"}
import { Ruba } from "@getruba/sdk";
const ruba = new Ruba({
accessToken: process.env.RUBA_ACCESS_TOKEN,
});
// Create a new customer
await ruba.customers.create({
email: "user@example.com",
name: "John Doe",
externalId: "user_123", // Your internal user ID (optional)
});
```
Use the `externalId` field to link Ruba customers with your internal user system. This lets you reference customers without storing Ruba's internal ID.
### Using External ID
If you set an `externalId` when creating the customer, you can use it in event ingestion in place of the Ruba customer ID:
```typescript theme={"system"}
// Instead of using customerId, use externalCustomerId
await ruba.events.ingest({
events: [{
name: "api_usage",
externalCustomerId: "user_123", // Your internal ID
metadata: { units: -10 }
}]
});
```
Learn more about [customer management](/features/customer-management).
## Step 3: Grant Credits by Ingesting a Negative Event
Now that you have a customer and a meter, grant credits by ingesting an event with a negative value.
### Using the Ruba SDK
```typescript icon="square-js" title="grant-credits.ts" theme={"system"}
import { Ruba } from "@getruba/sdk";
const ruba = new Ruba({
accessToken: process.env.RUBA_ACCESS_TOKEN,
});
async function grantCredits(customerId: string, credits: number) {
await ruba.events.ingest({
events: [
{
customerId,
name: "api_usage", // Must match your meter's filter name
metadata: {
units: -credits, // Negative value grants credits
},
},
],
});
console.log(`Granted ${credits} credits to customer ${customerId}`);
}
// Grant 10 credits to a customer
await grantCredits("cus_abc123", 10);
```
### Using External Customer ID
If you're using `externalId` for customer management:
```typescript icon="square-js" title="grant-credits-external.ts" theme={"system"}
import { Ruba } from "@getruba/sdk";
const ruba = new Ruba({
accessToken: process.env.RUBA_ACCESS_TOKEN,
});
async function grantCreditsToExternalUser(externalUserId: string, credits: number) {
await ruba.events.ingest({
events: [
{
name: "api_usage", // Must match your meter's filter name
externalCustomerId: externalUserId, // Use your internal ID
metadata: {
units: -credits, // Negative value grants credits
},
},
],
});
console.log(`Granted ${credits} credits to user ${externalUserId}`);
}
// Grant 10 credits using your internal user ID
await grantCreditsToExternalUser("user_123", 10);
```
## Step 4: Verify Credits Were Granted
Confirm that the credits were successfully granted to the customer.
### Using Customer Meters API
```typescript theme={"system"}
import { Ruba } from "@getruba/sdk";
const ruba = new Ruba({
accessToken: process.env.RUBA_ACCESS_TOKEN,
});
// Check customer's meter balance
const meters = await ruba.customerMeters.list({
customerId: "cus_abc123",
});
meters.items.filter((balance) => balance > 0).forEach((meter) => {
console.log(`${Math.abs(meter.balance)} credits available for ${meter.meter_id}.`);
});
```
### Example Usage Flow
```typescript theme={"system"}
// Initial state: Customer created, 0 balance
// Grant 10 credits: balance = 10
// Customer uses 3 units
await ruba.events.ingest({
events: [{
name: "api_usage",
customerId: "cus_abc123",
metadata: { units: 3 } // Positive value for usage
}]
});
// Balance is now 7 (7 credits remaining)
// Customer uses 8 more units
await ruba.events.ingest({
events: [{
name: "api_usage",
customerId: "cus_abc123",
metadata: { units: 8 }
}]
});
// Balance is now -1 (used 1 unit beyond credits)
```