Usage Metering

Report customer consumption to cloud marketplaces for accurate billing.

Overview

Usage metering allows you to report customer consumption data to AWS and Azure marketplaces. This is essential for products with usage-based pricing models where customers are charged based on actual consumption rather than flat subscription fees.

Automatum provides a unified API for reporting usage to both AWS Marketplace and Azure Marketplace, with built-in validation, queuing, and retry mechanisms.

How It Works

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  Your           │     │   Automatum     │     │   Marketplace   │
│  Application    │────▶│   Metering      │────▶│   (AWS/Azure)   │
│                 │     │   Service       │     │                 │
└─────────────────┘     └─────────────────┘     └─────────────────┘
        │                       │                       │
        │   Report Usage        │   Validate &          │   Confirm
        │   via API             │   Queue               │   Receipt
        └───────────────────────┴───────────────────────┘

Your application tracks customer usage
Usage is reported to Automatum via API
Automatum validates the data
Usage is queued and sent to the marketplace
Marketplace confirms receipt
Status updates in your dashboard

Supported Marketplaces

AWS Marketplace

Supported Product Types:

SaaS with usage-based pricing
SaaS contracts with consumption
AMI with metered pricing

Metering Method: AWS Marketplace Metering Service API

Timing Requirements:

Report promptly — Automatum stamps each AWS usage record at submission time, so AWS's "within 1 hour of usage" window is effectively auto-satisfied when you report soon after consumption
AWS limits BatchMeterUsage to 25 records per batch and requires positive integer quantities (enforced by AWS, not by Automatum)

Azure Marketplace

Supported Product Types:

SaaS offers with custom meters
Managed applications with metering

Metering Method: Azure Marketplace Metering Service API

Timing Requirements:

Must report within 24 hours of usage
One record per dimension per hour
effectiveStartTime must be in UTC

Setting Up Metering

Prerequisites

Before you can report usage:

Product configured for metering - Your marketplace listing must have metered dimensions defined
Active customer subscription - Customer must have an active entitlement
Cloud account connected - AWS or Azure account connected to Automatum
Dimensions synced - Product dimensions imported to Automatum

Step 1: Define Dimensions in Marketplace

AWS Marketplace:

When creating your product listing, define dimensions:

json

{
  "Dimensions": [
    {
      "Name": "Users",
      "Description": "Number of active users",
      "Key": "users",
      "Unit": "Units",
      "Types": ["Entitled"]
    },
    {
      "Name": "API Calls",
      "Description": "Number of API requests",
      "Key": "api_calls",
      "Unit": "Units",
      "Types": ["ExternallyMetered"]
    },
    {
      "Name": "Storage",
      "Description": "GB of storage used",
      "Key": "storage_gb",
      "Unit": "Units",
      "Types": ["ExternallyMetered"]
    }
  ]
}

Azure Marketplace:

Define custom meters in Partner Center:

json

{
  "planId": "premium",
  "billingDimensions": [
    {
      "id": "users",
      "displayName": "Active Users",
      "unitOfMeasure": "Users",
      "pricePerUnit": 10.00
    },
    {
      "id": "api_calls",
      "displayName": "API Calls",
      "unitOfMeasure": "1000 Calls",
      "pricePerUnit": 0.50
    },
    {
      "id": "storage_gb",
      "displayName": "Storage",
      "unitOfMeasure": "GB",
      "pricePerUnit": 0.10
    }
  ]
}

Step 2: Sync Product to Automatum

Navigate to Listings
Click Sync from AWS or Sync from Azure
Select your metered product
Verify dimensions are imported correctly

Step 3: Verify Customer Entitlement

Before reporting usage, ensure the customer has an active subscription:

bash

GET https://api.automatum.io/api/v1/entitlements?customer=cust_123
Authorization: Bearer YOUR_ACCESS_TOKEN

Response:

json

{
  "code": 200,
  "data": [
    {
      "id": "ent_456",
      "customerId": "cust_123",
      "listingId": "listing_789",
      "details": {
        "subscriptionStatus": "subscribed",
        "entries": [
          {
            "name": "api_calls",
            "units": 1,
            "price": ""
          }
        ]
      },
      "vendor": "aws"
    }
  ]
}

Reporting Usage

Via API

AWS Marketplace Usage:

bash

POST https://api.automatum.io/api/v1/metering
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json

{
  "vendor": "aws",
  "listingId": "listing_789",
  "details": {
    "customer": {
      "id": "cust_123"
    },
    "reportingDate": "2026-01-16",
    "charged": 150.00,
    "usages": [
      {
        "apiKey": "api_calls",
        "units": 15000,
        "title": "API Calls",
        "description": "Number of API requests",
        "per": "request",
        "price": "0.01"
      }
    ]
  }
}

Azure Marketplace Usage:

bash

POST https://api.automatum.io/api/v1/metering
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json

{
  "vendor": "azure",
  "listingId": "listing_789",
  "details": {
    "customer": {
      "id": "cust_123"
    },
    "reportingDate": "2026-01-16",
    "charged": 15.50,
    "usages": [
      {
        "apiKey": "api_calls",
        "units": 15.5,
        "title": "API Calls",
        "description": "Number of API requests",
        "per": "1000 calls",
        "price": "1.00",
        "planId": "premium"
      }
    ]
  }
}

Response:

json

{
  "code": 201,
  "data": {
    "id": "meter_abc123",
    "status": {
      "type": "pending",
      "message": "Metering data submitted successfully"
    }
  }
}

Via Dashboard

For manual or one-off usage reporting:

Navigate to Metering
Fill in the form:
- Select customer
- Select product
- Choose dimension
- Enter quantity
Click Submit

Metering Event Schema

Required Fields

Field	Type	Description
`vendor`	string	`aws` or `azure`
`listingId`	string	Automatum listing ID
`details.customer.id`	string	Automatum customer ID (required)
`details.reportingDate`	string	Date in YYYY-MM-DD format
`details.charged`	number	Total amount charged (can be 0)
`details.usages`	array	Array of usage objects (required)

Usage Object Fields

Field	Type	Description
`apiKey`	string	Dimension/API key identifier (required)
`units`	number	Usage quantity (required)
`title`	string	Display title for the usage
`description`	string	Description of the usage
`per`	string	Unit of measure (e.g., "request", "GB")
`price`	string	Price per unit
`planId`	string	Plan identifier (Azure only, optional)

Example Request Body

json

{
  "vendor": "aws",
  "listingId": "listing_789",
  "details": {
    "customer": {
      "id": "cust_123"
    },
    "reportingDate": "2026-01-16",
    "charged": 150.00,
    "usages": [
      {
        "apiKey": "api_calls",
        "units": 15000,
        "title": "API Calls",
        "description": "Number of API requests",
        "per": "request",
        "price": "0.01"
      },
      {
        "apiKey": "storage_gb",
        "units": 250,
        "title": "Storage",
        "description": "GB of storage used",
        "per": "GB",
        "price": "0.10"
      }
    ]
  }
}

Validation Rules

Automatum validates all metering events before submission:

Quantity Validation

Must be a positive number
AWS: BatchMeterUsage requires positive integer quantities (whole numbers only) — this is enforced by AWS, not by Automatum
Azure: Can be decimal (up to 5 decimal places)
Cannot exceed reasonable limits

Timestamp Validation

AWS: Automatum stamps each usage record at submission time (UTC), so AWS's "within the last 1 hour" requirement is effectively auto-satisfied when you report promptly — reportingDate is an Automatum record field and is not sent to AWS as the metering timestamp
Azure: Must be within last 24 hours
Reporting date must be valid and cannot be in the future

Dimension Validation

Dimension must exist in product
Dimension must be configured for metering
Customer must be entitled to dimension

Customer Validation

Customer must exist in Automatum
Customer must have active entitlement
Entitlement must not be expired

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 error and retry
`duplicate`	Already reported	None - informational

View Status

Via Dashboard:

Navigate to Metering
View all events with status indicators
Filter by status using the dropdown
Click on any event for details

Error Handling

Common Errors

INVALID_DIMENSION

json

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

Solution: Verify dimension key matches exactly what's in your product configuration.

NO_ENTITLEMENT

json

{
  "error": {
    "code": "NO_ENTITLEMENT",
    "message": "Customer does not have active entitlement for this product"
  }
}

Solution: Verify customer has purchased and has an active subscription.

TIMESTAMP_OUT_OF_RANGE

json

{
  "error": {
    "code": "TIMESTAMP_OUT_OF_RANGE",
    "message": "Timestamp must be within last 1 hour for AWS"
  }
}

Solution: Report usage within the allowed time window.

DUPLICATE_RECORD

json

{
  "error": {
    "code": "DUPLICATE_RECORD",
    "message": "Usage already reported for this customer/dimension/timestamp"
  }
}

Solution: This is informational - the usage was already recorded.

QUANTITY_INVALID

json

{
  "error": {
    "code": "QUANTITY_INVALID",
    "message": "Quantity must be a positive integer for AWS"
  }
}

Solution: Ensure quantity is a positive whole number (for AWS).

Retry Logic

Automatum automatically retries failed submissions:

Attempt	Delay	Notes
1	Immediate	First attempt
2	1 minute	After first failure
3	5 minutes	Exponential backoff
4	30 minutes	Continued backoff
5	2 hours	Final automatic retry

After 5 failures:

Event marked as permanently failed
Alert sent to organization admins
Manual retry available in dashboard

Manual Retry

To retry a failed event:

Go to Metering
Filter by status: failed
Click on the failed event
Review error details
Click Retry

::: note API Limitation The OAuth API currently only supports creating metering events. To view status, retry failed events, or manage metering events, use the Automatum dashboard. :::

Best Practices

1. Report Frequently

Don't wait until the end of the billing period:

Report at least hourly
More frequent = more accurate billing
Reduces risk of missing reporting windows

2. Use Idempotency Keys

Prevent duplicate submissions:

bash

POST https://api.automatum.io/api/v1/metering
Authorization: Bearer YOUR_ACCESS_TOKEN
Idempotency-Key: cust_123-api_calls-2026-01-16T10:00:00Z
Content-Type: application/json

{
  "vendor": "aws",
  "listingId": "listing_789",
  "details": {
    "customer": {
      "id": "cust_123"
    },
    "reportingDate": "2026-01-16",
    "charged": 150.00,
    "usages": [
      {
        "apiKey": "api_calls",
        "units": 15000,
        "title": "API Calls",
        "description": "Number of API requests",
        "per": "request",
        "price": "0.01"
      }
    ]
  }
}

3. Implement Queuing

Buffer usage locally before reporting:

javascript

const usageQueue = [];

// Collect usage throughout the hour
function recordUsage(customerId, dimension, quantity) {
  usageQueue.push({ customerId, dimension, quantity, timestamp: new Date() });
}

// Report hourly
setInterval(async () => {
  for (const usage of usageQueue) {
    await reportToAutomatum(usage);
  }
  usageQueue.length = 0;
}, 3600000); // Every hour

4. Monitor for Failures

Set up alerts for metering failures:

Go to Settings > Notifications
Enable Metering Failure alerts
Add recipients (technical team)
Choose notification channels

5. Validate Before Sending

Check data before reporting:

javascript

function validateMeteringEvent(event) {
  if (event.quantity <= 0) {
    throw new Error('Quantity must be positive');
  }
  if (event.vendor === 'aws' && !Number.isInteger(event.quantity)) {
    throw new Error('AWS requires integer quantities');
  }
  if (new Date(event.timestamp) > new Date()) {
    throw new Error('Timestamp cannot be in the future');
  }
  return true;
}

6. Keep Audit Logs

Maintain records of all usage:

Log all metering events locally
Store submission responses
Track status changes
Retain for billing disputes

API Reference

Create Metering Event

Endpoint: POST https://api.automatum.io/api/v1/metering

Required Scope: write:metering

Request:

bash

POST https://api.automatum.io/api/v1/metering
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json

{
  "vendor": "aws",
  "listingId": "listing_789",
  "details": {
    "customer": {
      "id": "cust_123"
    },
    "reportingDate": "2026-01-16",
    "charged": 150.00,
    "usages": [
      {
        "apiKey": "api_calls",
        "units": 15000,
        "title": "API Calls",
        "description": "Number of API requests",
        "per": "request",
        "price": "0.01"
      }
    ]
  }
}

Response:

json

{
  "code": 201,
  "data": {
    "id": "meter_abc123",
    "status": {
      "type": "pending",
      "message": "Metering data submitted successfully"
    }
  }
}

::: note Viewing Metering Events To view metering event status, history, or manage events, use the Automatum dashboard. The OAuth API currently only supports creating new metering events. :::

Troubleshooting

Usage Not Appearing in Marketplace

Check metering event status in Automatum
Verify customer has active entitlement
Confirm dimension configuration matches
Allow up to 24 hours for processing
Check marketplace console directly

Incorrect Billing Amounts

Verify quantity units match dimension configuration
Check for duplicate submissions
Review timestamp accuracy
Compare with local usage logs

High Failure Rate

Review error messages in failed events
Verify API credentials are valid
Check network connectivity
Ensure customer entitlements are active
Contact support if persistent

Next Steps

Need Help?

Contact hello@automatum.io for metering assistance.

Usage Metering ​

Overview ​

How It Works ​

Supported Marketplaces ​

AWS Marketplace ​

Azure Marketplace ​

Setting Up Metering ​

Prerequisites ​

Step 1: Define Dimensions in Marketplace ​

Step 2: Sync Product to Automatum ​

Step 3: Verify Customer Entitlement ​

Reporting Usage ​

Via API ​

Via Dashboard ​

Metering Event Schema ​

Required Fields ​

Usage Object Fields ​

Example Request Body ​

Validation Rules ​

Quantity Validation ​

Timestamp Validation ​

Dimension Validation ​

Customer Validation ​

Metering Status ​

View Status ​

Error Handling ​

Common Errors ​

Retry Logic ​

Manual Retry ​

Best Practices ​

1. Report Frequently ​

2. Use Idempotency Keys ​

3. Implement Queuing ​

4. Monitor for Failures ​

5. Validate Before Sending ​

6. Keep Audit Logs ​

API Reference ​

Create Metering Event ​

Troubleshooting ​

Usage Not Appearing in Marketplace ​

Incorrect Billing Amounts ​

High Failure Rate ​

Next Steps ​

Need Help? ​

Usage Metering

Overview

How It Works

Supported Marketplaces

AWS Marketplace

Azure Marketplace

Setting Up Metering

Prerequisites

Step 1: Define Dimensions in Marketplace

Step 2: Sync Product to Automatum

Step 3: Verify Customer Entitlement

Reporting Usage

Via API

Via Dashboard

Metering Event Schema

Required Fields

Usage Object Fields

Example Request Body

Validation Rules

Quantity Validation

Timestamp Validation

Dimension Validation

Customer Validation

Metering Status

View Status

Error Handling

Common Errors

Retry Logic

Manual Retry

Best Practices

1. Report Frequently

2. Use Idempotency Keys

3. Implement Queuing

4. Monitor for Failures

5. Validate Before Sending

6. Keep Audit Logs

API Reference

Create Metering Event

Troubleshooting

Usage Not Appearing in Marketplace

Incorrect Billing Amounts

High Failure Rate

Next Steps

Need Help?