S3 Strategy

Charging customers for storage means knowing exactly how many bytes each one wrote — without bolting a counter onto every upload path. The S3 Strategy wraps the official AWS S3 client so that every PutObject you send is metered for you, then forwarded to Macropay as a usage event keyed to a customer. From there, a meter aggregates those bytes and a metered product price turns them into a bill. Because Macropay is your Merchant of Record, the invoice that lands also carries the right sales tax / VAT for the buyer’s jurisdiction — collected and remitted on your behalf, off your liability.

Pairs naturally with the Stream Strategy when you also serve downloads, and with the LLM Strategy if storage sits behind an AI workload.

What you’ll need

A Macropay organization access token (MACROPAY_ACCESS_TOKEN).
An S3-compatible bucket and credentials (AWS S3, Minio, R2, or any S3-API store).
A customer identifier to attribute each upload to.

Install

pnpm add @macropayments/ingestion @aws-sdk/client-s3

Wrap the S3 client

You build the ingestion pipeline once — pass it your S3Client, choose the S3Strategy, and name the event (s3-uploads below). At request time, .client({ customerId }) hands you a drop-in S3 client that behaves exactly like the original, except every write it sends is measured and reported.

import { Ingestion } from "@macropayments/ingestion";
import { S3Strategy } from "@macropayments/ingestion/strategies/S3";
import { PutObjectCommand, S3Client } from "@aws-sdk/client-s3";

const s3Client = new S3Client({
  region: process.env.AWS_REGION,
  endpoint: process.env.AWS_ENDPOINT_URL,
  credentials: {
    accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
  },
});

// Build the metered S3 pipeline once, reuse it per request.
const s3Ingestion = Ingestion({ accessToken: process.env.MACROPAY_ACCESS_TOKEN })
  .strategy(new S3Strategy(s3Client))
  .ingest("s3-uploads");

export async function POST(request: Request) {
  try {
    // Resolve a customer-scoped S3 client so every byte is attributed correctly.
    const s3 = s3Ingestion.client({
      customerId: request.headers.get("X-Macropay-Customer-Id") ?? "",
    });

    // Persisting an exported audit log — billed by size, no extra plumbing.
    await s3.send(
      new PutObjectCommand({
        Bucket: process.env.AWS_BUCKET_NAME,
        Key: `audit-logs/${crypto.randomUUID()}.json`,
        Body: JSON.stringify({
          event: "invoice.exported",
          invoiceId: "inv_8f21",
          rows: 4096,
        }),
        ContentType: "application/json",
      })
    );

    return Response.json({});
  } catch (error) {
    return Response.json({ error: error.message });
  }
}

Set customerId from whatever you trust as the source of truth — a header, a verified session, or your auth context. Macropay matches it to the customer record that owns the meter, so attribution stays accurate even under concurrency.

What gets sent

Each wrapped PutObject emits one usage event. The strategy fills in metadata.bytes automatically; the rest describes the object so you can audit, filter, or build a meter on any field.

{
  "customerId": "123",
  "name": "s3-uploads",
  "metadata": {
    "bytes": 100,
    "bucket": "my-bucket",
    "key": "my-key",
    "contentType": "application/text"
  }
}

Field	Meaning
`customerId`	Customer the upload is billed to
`name`	Event name you passed to `.ingest()`
`metadata.bytes`	Size of the written object — the usual metered value
`metadata.bucket`	Destination bucket
`metadata.key`	Object key
`metadata.contentType`	MIME type of the object

Turn bytes into revenue

Create a meter

Define a meter that filters on name = "s3-uploads" and aggregates metadata.bytes. Switch the aggregation to a COUNT of events if you’d rather bill per upload than per byte.

Attach a metered price

Add a metered price to a product — for example, a per-GB rate, or a tier that includes a free allowance before usage charges begin.

Let Macropay close the loop

Usage rolls up automatically. At billing time Macropay charges the customer, applies the correct sales tax / VAT for their location, and remits it as Merchant of Record — so storage revenue never expands your tax footprint.

Beyond storage: metering agents

The same wrap-and-meter pattern powers Macropay’s AI billing. When an autonomous agent stages artifacts in S3 — render outputs, scraped corpora, generated reports — those writes become billable usage with zero extra instrumentation, and you can bill by usage, activity, or outcome rather than flat seats. Pair S3 metering with the event ingestion API to attribute both the work an agent does and the value it produces.

Need a metering pattern we don’t cover yet? Reach us at support@macropay.ai and we’ll help you wire it up.

Bootup

Features

Integrate

Merchant of Record (MoR)

What you’ll need

Install

Wrap the S3 client

What gets sent

Turn bytes into revenue

Beyond storage: metering agents

​What you’ll need

​Install

​Wrap the S3 client

​What gets sent

​Turn bytes into revenue

​Beyond storage: metering agents

What you’ll need

Install

Wrap the S3 client

What gets sent

Turn bytes into revenue

Beyond storage: metering agents