How to Grant Meter Credits Before Purchase

Why pre-fund a balance?

Sometimes the meter needs to start in the green before a single dollar changes hands. A free trial that hands out 1,000 tokens, a launch promo that drops bonus API calls into early accounts, or an AI agent you want to let run a few tasks before billing kicks in — all of these are the same primitive: a credit balance that exists ahead of any purchase. Macropay models this with metered usage. You seed a customer’s meter with credits, then let normal usage draw it down. Because Macropay is the merchant of record, the moment that customer does convert to a paid order, sales tax and VAT are calculated and remitted for you — the pre-funded balance and the eventual invoice live in the same system. Common scenarios:

Use case	Example
Trial allowance	New signup gets 500 free API calls
Promotional grant	”Launch week” accounts get 2,000 bonus units
Sales demo / POC	Prospect’s sandbox seeded with credits
Agent starter balance	An AI agent gets a budget before its first billable run

The mechanic: a negative event on a Sum meter

A meter with Sum aggregation simply adds up the values of every event it matches. Usage events carry a positive value and push the total up; a credit grant carries a negative value and pushes it down. That sign convention is the whole trick: the running sum represents consumption, so a negative running sum means the customer has unused credit in reserve. Each real usage event nudges it back toward zero, and once it crosses zero, billable usage begins.

Reading the balanceIngest -1000 on a Sum meter and the meter total becomes -1000. As the customer consumes, the total climbs: -1000 → -700 → 0. While the total is negative, its absolute value is the credit still available.

What you’ll need

A meter using Sum aggregation (created below)
A customer record — or your own externalId to reference one
A Macropay access token (MACROPAY_ACCESS_TOKEN)

Step 1 — Create a Sum meter

The meter defines which events count and how they’re aggregated.

Open the Meters list

In the dashboard sidebar, go to Products → Meters.

Configure the meter

Click Create Meter and set:

Name — something descriptive, e.g. API Calls or Render Minutes
Filter — match your usage events, e.g. event name equals api_usage
Aggregation — choose Sum, then enter the property to total (e.g. units)

Aggregation must be Sum for the credit mechanic to work. Count, max, or unique aggregations don’t net positive and negative events against each other.

Save it

Save the meter and keep the event name handy — your ingested events must match the filter.

See how meters aggregate events for filter and aggregation details.

Step 2 — Make sure the customer exists

You can grant credits to a Macropay customer ID or to your own externalId. Create the customer first if they aren’t in Macropay yet.

From the dashboard

Open Customers

Click Customers in the sidebar.

Add the customer

Click Add Customer and provide:

Email (required)
Name (optional)
External ID — your own user ID, e.g. user_8842 (optional but recommended)

Save

Save and copy the Customer ID.

From the API

create-customer.ts

import { Macropay } from "@macropayments/sdk";

const macropay = new Macropay({
  accessToken: process.env.MACROPAY_ACCESS_TOKEN,
});

await macropay.customers.create({
  email: "ada@hooli.dev",
  name: "Ada Pinsky",
  externalId: "user_8842", // your internal user ID (optional)
});

Set externalId so you can address customers by your identifier everywhere — no need to store Macropay’s IDs in your database. Pass it as externalCustomerId when ingesting events.

Step 3 — Grant the credits

Ingest a single event with a negative value. This is the same events.ingest call you’d use for real usage — only the sign differs.

By Macropay customer ID

grant-credits.ts

import { Macropay } from "@macropayments/sdk";

const macropay = new Macropay({
  accessToken: process.env.MACROPAY_ACCESS_TOKEN,
});

async function grantCredits(customerId: string, credits: number) {
  await macropay.events.ingest({
    events: [
      {
        customerId,
        name: "api_usage", // must match the meter's filter
        metadata: {
          units: -credits, // negative value = credit grant
        },
      },
    ],
  });

  console.log(`Granted ${credits} credits to ${customerId}`);
}

// Seed a new trial with 1,000 credits
await grantCredits("cus_abc123", 1000);

By your own external ID

grant-credits-external.ts

import { Macropay } from "@macropayments/sdk";

const macropay = new Macropay({
  accessToken: process.env.MACROPAY_ACCESS_TOKEN,
});

async function grantCreditsToExternalUser(externalUserId: string, credits: number) {
  await macropay.events.ingest({
    events: [
      {
        name: "api_usage", // must match the meter's filter
        externalCustomerId: externalUserId, // your internal ID
        metadata: {
          units: -credits, // negative value = credit grant
        },
      },
    ],
  });

  console.log(`Granted ${credits} credits to ${externalUserId}`);
}

// Promo: hand "launch week" signups a 2,000-unit bonus
await grantCreditsToExternalUser("user_8842", 2000);

Step 4 — Confirm the balance

Read the customer’s meters back. A negative balance means credits are still in reserve, so the credits remaining is Math.abs(balance).

check-balance.ts

import { Macropay } from "@macropayments/sdk";

const macropay = new Macropay({
  accessToken: process.env.MACROPAY_ACCESS_TOKEN,
});

const meters = await macropay.customerMeters.list({
  customerId: "cus_abc123",
});

meters.items
  .filter((meter) => meter.balance < 0) // negative balance = unused credit
  .forEach((meter) => {
    console.log(`${Math.abs(meter.balance)} credits available on ${meter.meter_id}`);
  });

How the balance moves

Once seeded, the meter behaves like any other — positive events are real usage that draws the reserve down:

lifecycle.ts

// Start: customer created, meter total = 0

// Grant 1,000 credits → total = -1000 (1,000 available)
await macropay.events.ingest({
  events: [{ name: "api_usage", customerId: "cus_abc123", metadata: { units: -1000 } }],
});

// Customer makes 300 API calls → total = -700 (700 available)
await macropay.events.ingest({
  events: [{ name: "api_usage", customerId: "cus_abc123", metadata: { units: 300 } }],
});

// Customer makes 750 more → total = 50 (credits exhausted, 50 units now billable)
await macropay.events.ingest({
  events: [{ name: "api_usage", customerId: "cus_abc123", metadata: { units: 750 } }],
});

Billing AI agents this way. The same negative-event grant gives an agent a starter budget before its first paid task. Because activity, usage, and outcome all flow through metered billing, the credits a free agent burns sit in the same ledger as the revenue it later earns — so agentic margin (billed revenue vs. AI cost) stays accurate from the very first run.

Getting Started

Guides

How to Grant Meter Credits Before Purchase

Why pre-fund a balance?

The mechanic: a negative event on a Sum meter

What you’ll need

Step 1 — Create a Sum meter

Step 2 — Make sure the customer exists

From the dashboard

From the API

Step 3 — Grant the credits

By Macropay customer ID

By your own external ID

Step 4 — Confirm the balance

How the balance moves

​Why pre-fund a balance?

​The mechanic: a negative event on a Sum meter

​What you’ll need

​Step 1 — Create a Sum meter

​Step 2 — Make sure the customer exists

​From the dashboard

​From the API

​Step 3 — Grant the credits

​By Macropay customer ID

​By your own external ID

​Step 4 — Confirm the balance

​How the balance moves

Why pre-fund a balance?

The mechanic: a negative event on a Sum meter

What you’ll need

Step 1 — Create a Sum meter

Step 2 — Make sure the customer exists

From the dashboard

From the API

Step 3 — Grant the credits

By Macropay customer ID

By your own external ID

Step 4 — Confirm the balance

How the balance moves