Usage Metering

Report customer usage to cloud marketplaces for accurate billing and compliance.

Overview

Automatum simplifies usage-based pricing by providing a unified API for reporting consumption to both AWS and Azure Marketplaces. Track customer usage, validate metering data, and ensure accurate billing.

What is Metering?

Metering allows you to charge customers based on their actual usage of your product. Common metering dimensions include:

API calls
Data processed (GB, TB)
Users/seats
Compute hours
Storage consumed
Transactions processed
Features used

How Metering Works

mermaid

graph LR
    A[Your Application] -->|Reports Usage| B[Automatum]
    B -->|Validates Data| C[Automatum Queue]
    C -->|Batches & Sends| D[AWS/Azure]
    D -->|Confirms Receipt| B
    B -->|Updates Status| E[Dashboard]

Your application reports usage to Automatum
Automatum validates and queues the data
Usage is batched and sent to the marketplace
Marketplace confirms receipt
Status updates in your dashboard

Setting Up Metering

Define Dimensions

First, define your metering dimensions in your product listing:

AWS Marketplace Example:

json

{
  "dimensions": [
    {
      "key": "api_calls",
      "name": "API Calls",
      "description": "Number of API requests",
      "unit": "Requests"
    },
    {
      "key": "data_processed",
      "name": "Data Processed",
      "description": "Amount of data processed",
      "unit": "GB"
    }
  ]
}

Azure Marketplace Example:

json

{
  "planId": "premium",
  "meters": [
    {
      "id": "api_calls",
      "displayName": "API Calls",
      "category": "Usage",
      "unit": "Requests"
    }
  ]
}

Configure Product Registration

In Automatum:

Go to Listings > Select your product
Navigate to Metering Configuration
Verify dimensions are synced from marketplace
Set up validation rules
Configure batch settings

Reporting Usage

Via API

Report usage programmatically using the Automatum OAuth API:

bash

# Get OAuth token first
TOKEN=$(curl -X POST https://api.automatum.io/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "scope=write:metering" | jq -r '.access_token')

# Submit metering data
curl -X POST https://api.automatum.io/api/v1/metering \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "vendor": "aws",
    "listingId": "listing-uuid",
    "details": {
      "customer": {
        "id": "customer-uuid"
      },
      "reportingDate": "2026-01-16",
      "charged": 100.00,
      "usages": [
        {
          "apiKey": "api_calls",
          "units": 1000,
          "title": "API Calls",
          "description": "Number of API requests",
          "per": "request",
          "price": "0.10"
        }
      ]
    }
  }'

Required Fields:

vendor: Marketplace platform (aws or azure)
listingId: Your product listing ID in Automatum
details.customer.id: Customer ID in Automatum
details.reportingDate: Date in YYYY-MM-DD format
details.charged: Total amount charged for this metering event
details.usages: Array of usage records with apiKey, units, and pricing info

Via Dashboard

For manual or one-off reporting:

Navigate to Metering
Fill in the form:
- Customer: Select from dropdown
- Product/Listing: Select from dropdown (filters to products with metering dimensions)
- Reporting Date: Date for the usage report
- Quantity: Enter quantity for each usage dimension
Click Submit

Pricing

If the customer has a private offer for the selected product, the dashboard will display custom pricing from the private offer. Otherwise, it shows the listing's default pricing.

Metering Data Structure

Current Format

typescript

interface MeteringEvent {
  vendor: 'aws' | 'azure';
  listingId: string;             // Your product listing ID in Automatum
  organizationId?: string;       // Auto-populated from OAuth token
  details: {
    customer: {
      id: string;                // Customer ID in Automatum
      cloudIdentifier?: string;  // Auto-populated
      details?: object;          // Auto-populated
    };
    reportingDate: string;       // Date in YYYY-MM-DD format
    charged: number;             // Total amount charged
    usages: Array<{
      apiKey: string;            // Dimension key from listing
      units: number;             // Usage quantity
      title: string;             // Dimension display name
      description?: string;      // Usage description
      per: string;               // Unit description (e.g., "request", "GB")
      price: string;             // Price per unit
    }>;
  };
  status?: {
    type: 'pending' | 'processing' | 'confirmed' | 'failed';
    message?: string;
  };
}

Customer Data

The API automatically enriches customer data (cloudIdentifier, details) from the customer ID. You only need to provide details.customer.id.

Validation Rules

Automatum validates metering data before sending to marketplaces:

Quantity Validation

Must be a positive number
Cannot exceed dimension limits
Precision based on dimension type

Date Validation

Reporting date must be in YYYY-MM-DD format
Cannot be in the future
Must be within marketplace backfill windows:
- AWS: Recent dates only
- Azure: Up to 24 hours
Date is used for billing period calculation

Customer Validation

Customer must have active entitlement
Entitlement must cover the dimension
Subscription must not be expired

Duplicate Detection

Prevents duplicate submissions
Uses idempotency keys
Configurable deduplication window

Metering Status

Track the status of your metering events:

Status	Description	Action Required
`pending`	Queued for submission	None - processing
`submitted`	Sent to marketplace	None - awaiting confirmation
`confirmed`	Accepted by marketplace	None - success
`failed`	Rejected by marketplace	Review and resubmit
`duplicate`	Already reported	None - informational

Viewing Status

bash

# Get all metering events
GET /api/metering-event
Authorization: Bearer YOUR_API_KEY

# Filter by status
GET /api/metering-event?status=failed

# Filter by listing
GET /api/metering-event?listing=listing_456

Error Handling

Common Errors

Error: Invalid Dimension

json

{
  "error": "INVALID_DIMENSION",
  "message": "Dimension 'invalid_key' not found in product listing",
  "dimension": "invalid_key"
}

Solution: Verify dimension exists in product configuration

Error: No Active Entitlement

json

{
  "error": "NO_ENTITLEMENT",
  "message": "Customer does not have active entitlement",
  "customerId": "cust_123"
}

Solution: Verify customer has purchased your product

Error: Date Out of Range

json

{
  "error": "DATE_INVALID",
  "message": "Reporting date must be within allowed backfill window",
  "reportingDate": "2026-01-15"
}

Solution: Report usage for recent dates within marketplace limits

Retry Logic

Automatum automatically retries failed submissions:

Immediate retry: For transient errors
Exponential backoff: 1min, 5min, 15min, 1hr
Max retries: 5 attempts
Manual retry: Available in dashboard

Best Practices

1. Report Frequently

Report usage at least hourly
More frequent = more accurate billing
Reduces risk of missing data

2. Handle Failures Gracefully

typescript

try {
  const response = await fetch('https://api.automatum.io/api/v1/metering', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(meteringData)
  });
  
  if (!response.ok) {
    throw new Error(`Metering failed: ${response.status}`);
  }
} catch (error) {
  // Log error
  console.error('Metering failed:', error);
  // Queue for retry
  await retryQueue.add(meteringData);
}

3. Monitor Usage Trends

Set up alerts for unusual patterns
Track failed submissions
Review validation errors

4. Test Before Production

Use marketplace sandbox environments
Validate data formats
Test error scenarios

Analytics

View metering analytics in the dashboard:

Usage Trends

Historical usage by dimension
Customer consumption patterns
Peak usage times
Growth metrics

Billing Impact

Projected revenue
Usage-based charges
Comparison to quotas

Reliability Metrics

Success rate
Failed submissions
Retry statistics
Latency

Webhooks

Receive real-time notifications for metering events:

typescript

// Webhook payload example
{
  "event": "metering.confirmed",
  "data": {
    "meteringEventId": "evt_123",
    "customerId": "cust_456",
    "dimension": "api_calls",
    "quantity": 1000,
    "status": "confirmed",
    "timestamp": "2026-01-16T10:00:00Z"
  }
}

Configure webhooks in Settings > Webhooks

API Reference

Create Metering Event

bash

POST /api/v1/metering
Content-Type: application/json
Authorization: Bearer YOUR_TOKEN

{
  "vendor": "aws",
  "listingId": "listing-uuid",
  "details": {
    "customer": {
      "id": "customer-uuid"
    },
    "reportingDate": "2026-01-16",
    "charged": 100.00,
    "usages": [
      {
        "apiKey": "api_calls",
        "units": 1000,
        "title": "API Calls",
        "description": "Number of API requests",
        "per": "request",
        "price": "0.10"
      }
    ]
  }
}

Response:

json

{
  "code": 201,
  "data": {
    "id": "metering-event-uuid",
    "status": {
      "type": "pending"
    },
    "message": "Metering data submitted successfully"
  }
}

Get Metering Events

bash

GET /metering-event?status=confirmed&listing=listing-uuid
Authorization: Bearer YOUR_TOKEN

Update Metering Event Status

bash

PUT /meteringEvent/:id
Content-Type: application/json
Authorization: Bearer YOUR_TOKEN

{
  "status": {
    "type": "confirmed",
    "message": "Confirmed by marketplace"
  }
}

Compliance

Data Retention

Metering records retained for 7 years
Required for audit purposes
Exportable for compliance

Audit Trail

Every metering event includes:

Who reported it
When it was reported
What was reported
Marketplace response
Any modifications

Troubleshooting

Usage Not Appearing in Marketplace

Check metering event status
Verify customer entitlement
Confirm dimension configuration
Review marketplace console

Duplicate Usage Charges

Check for duplicate submissions
Review idempotency keys
Verify timestamp uniqueness
Contact support if needed

Missing Usage Data

Verify application is reporting correctly
Check API authentication
Review error logs
Set up monitoring alerts

Next Steps

Need Help?

Contact support@automatum.io for assistance with metering setup and troubleshooting.

Usage Metering ​

Overview ​

What is Metering? ​

How Metering Works ​

Setting Up Metering ​

Define Dimensions ​

Configure Product Registration ​

Reporting Usage ​

Via API ​

Via Dashboard ​

Metering Data Structure ​

Current Format ​

Validation Rules ​

Quantity Validation ​

Date Validation ​

Customer Validation ​

Duplicate Detection ​

Metering Status ​

Viewing Status ​

Error Handling ​

Common Errors ​

Retry Logic ​

Best Practices ​

1. Report Frequently ​

2. Handle Failures Gracefully ​

3. Monitor Usage Trends ​

4. Test Before Production ​

Analytics ​

Usage Trends ​

Billing Impact ​

Reliability Metrics ​

Webhooks ​

API Reference ​

Create Metering Event ​

Get Metering Events ​

Update Metering Event Status ​

Compliance ​

Data Retention ​

Audit Trail ​

Troubleshooting ​

Usage Not Appearing in Marketplace ​

Duplicate Usage Charges ​

Missing Usage Data ​

Next Steps ​

Need Help? ​

Usage Metering

Overview

What is Metering?

How Metering Works

Setting Up Metering

Define Dimensions

Configure Product Registration

Reporting Usage

Via API

Via Dashboard

Metering Data Structure

Current Format

Validation Rules

Quantity Validation

Date Validation

Customer Validation

Duplicate Detection

Metering Status

Viewing Status

Error Handling

Common Errors

Retry Logic

Best Practices

1. Report Frequently

2. Handle Failures Gracefully

3. Monitor Usage Trends

4. Test Before Production

Analytics

Usage Trends

Billing Impact

Reliability Metrics

Webhooks

API Reference

Create Metering Event

Get Metering Events

Update Metering Event Status

Compliance

Data Retention

Audit Trail

Troubleshooting

Usage Not Appearing in Marketplace

Duplicate Usage Charges

Missing Usage Data

Next Steps

Need Help?