Sarvagya Pandey
Marketing Specialist
How to Validate Metered Billing APIs on Azure
Learn how to validate metered billing APIs on Azure to ensure accurate billing and avoid unexpected costs for your customers.
Want to ensure your Azure Marketplace billing is accurate and reliable? Here's how you can validate metered billing APIs step-by-step to avoid errors, disputes, and unexpected costs. Metered billing APIs let you charge customers based on actual usage instead of fixed fees, but proper validation is key before going live. Here's what you need to know:
- Set Up a Test Environment: Create a separate DEV offer to test billing without affecting production.
- Define Billing Dimensions: Configure up to 30 custom dimensions per plan to track usage and charges.
- Secure Authentication: Use access tokens with HTTPS and verify permissions for your Microsoft Entra app.
- Test API Events: Submit usage events within Azure's strict timing rules (e.g., 24-hour reporting window).
- Check API Responses: Ensure events are recorded successfully and resolve errors like duplicates or invalid data.
- Fix Common Issues: Troubleshoot authentication errors, timing mismatches, and data discrepancies.
By following these steps, you can validate your metered billing APIs and ensure a smooth launch. Tools like WeTransact can automate testing, monitor errors, and simplify compliance.
Quick Tip: Always aggregate usage data locally and submit only events exceeding base fees to avoid overbilling.
Learn how to configure, test, and troubleshoot your metered billing setup for a seamless Azure Marketplace experience.
Building for marketplace:An introduction to the Metered Billing Accelerator
Setting Up Your Validation Environment
Creating a dedicated validation environment is essential for keeping your testing separate from production. This approach helps avoid costly mistakes and ensures a smooth transition to live operations.
Creating a Test Offer
Microsoft's official guidance emphasizes the importance of a separate testing setup:
"We recommend that you create a separate test and development (DEV) offer as a low-risk way to test before you publish your production (PROD) offer."
To implement this, you’ll need to register two Microsoft Entra applications - one for your DEV offer and another for your PROD offer. This setup ensures that any testing activities won’t interfere with live customers or result in unwanted charges.
When naming your DEV offer, use the same base alias as your production offer and append _test to it (e.g., "DataAnalytics_test"). Also, make your test plan private, granting access only to developers and testers.
Here’s a quick comparison of the key configuration differences between DEV and PROD offers:
| Setting | DEV Offer | PROD Offer |
|---|---|---|
| Landing page URL | Enter your dev/test endpoint | Enter your production endpoint |
| Connection webhook | Enter your dev/test endpoint | Enter your production endpoint |
| Microsoft Entra tenant ID | Enter your test app registration tenant ID | Enter your production app registration tenant ID |
| Microsoft Entra application ID | Enter your test app registration application ID | Enter your production app registration application ID |
To keep testing costs low, set your DEV offer plans to zero or a minimal price (e.g., $0.01 per unit). You’ll also need to configure billing dimensions, which determine how usage events translate into charges.
Setting Up Billing Dimensions
Billing dimensions are critical for defining how customers are charged. These dimensions communicate usage data to Microsoft, which calculates the final billing amounts [2]. It’s important to finalize your billing dimensions before publishing, as some settings can’t be changed once the offer is live.
While billing dimensions apply across all plans in an offer, certain attributes can vary. For instance, you might have an "API Calls" dimension that’s shared across Basic and Premium plans, but with different pricing levels for each.
To simplify pricing adjustments across regions, you can use Partner Center’s pricing data import and export tools. This ensures consistent pricing no matter where your customers are located.
For testing purposes, create a private plan with custom dimensions priced minimally. This allows you to validate your billing logic without incurring significant costs.
Configuring Authentication
With your test offer and billing dimensions in place, the next step is to set up secure authentication for API communication.
The Marketplace Metering Service APIs rely on access tokens to verify the identity of ISVs making API calls. These tokens are included in the authorization header as "Bearer <access_token>". To ensure secure data transmission, use HTTPS with TLS version 1.2 or higher.
The process for retrieving access tokens depends on the type of offer you’re working with. For SaaS offers, tokens are usually obtained through HTTP POST requests. Managed Applications, however, may require different authentication methods tailored to their specific needs.
A real-world example highlights the importance of accurate configuration: an incorrect Resource ID caused an authentication error with the message:
"error": "invalid_resource", "error_description": "AADSTS500011: The resource principal named 00001111-aaaa-2222-bbbb-3333cccc4444 was not found in the tenant named AppsCode Inc."
The issue was resolved by using the correct Resource ID - 20e940b3-4c77-4b0b-9a53-9e16a1b010a7 - sourced from alternative documentation.
Make sure your Microsoft Entra application registration has the necessary permissions and is properly linked to your Azure subscription. This connection allows Azure Cost Management + Billing to monitor and manage your application’s metered usage costs effectively.
Before moving on to API event testing, thoroughly validate your authentication setup to avoid disruptions caused by configuration errors.
Testing Metered Billing API Events
After setting up authentication, the next step is to test sending usage events to Azure's Marketplace Metering Service. This involves crafting precise API calls, adhering to strict timing rules, and interpreting response codes to ensure your billing integration operates smoothly.
Creating API Calls
Accurate API calls are the backbone of metered billing tests. Azure offers two endpoints for this purpose: the Single Usage Event API for individual events and the Batch Usage Event API for handling multiple events at once.
For single usage events, your HTTP POST request must include essential headers like:
- API version: Use
2018‑08‑31. - Content type: Set to
application/json. - Authorization: Include the token in the format
Bearer <access_token>. - Tracking IDs: Use
x‑ms‑requestidandx‑ms‑correlationidfor debugging and monitoring.
When testing batch events, you can send up to 25 events in one request. This is especially useful for validating usage across multiple resources or different time periods. Although the headers remain the same as those for single events, the batch API allows you to group related usage events into one payload.
Your request payload must include accurate resource details. For SaaS offers, the resourceId refers to the SaaS subscription ID, while for Azure Managed Applications, it represents the resource group ID. The planId must match your offer's plan configuration, and the dimension field should align with the dimensions you defined during setup.
To ensure your billing logic works correctly, make sure the events exceed any base fees so that charges are triggered. Additionally, confirm that your events meet Azure's timing requirements.
Validating Time Requirements
Azure enforces strict timing rules for usage events, which must be followed for successful API validation:
- 24-Hour Window: Events can only be submitted for usage that occurred in the past 24 hours. Anything older will result in a 400 Bad Request error.
- One Event Per Hour: Only one usage event is allowed per resource and dimension per hour. If multiple units of usage occur within an hour, aggregate them into a single event to avoid duplicate billing.
The effectiveStartTime field must be in UTC format and fall within the 24-hour window. This timestamp reflects when the usage occurred, not when the event is reported. Accurate timestamps are essential for proper billing cycles and customer invoices.
For applications with frequent usage, aggregate usage data locally before submitting events. This reduces the number of API calls while staying compliant with the one-event-per-hour rule. Once timing is validated, move on to analyzing API response codes.
Checking API Responses
API response codes provide instant feedback on the success or failure of your requests. A 200 OK response means the usage event was successfully recorded, confirming your billing integration is working.
Pay close attention to error responses:
- 409 Conflict: Indicates duplicate events. Ensure each event is unique before submitting.
- 400 Bad Request: Points to invalid data or timing issues. Double-check your payload format and ensure the event falls within the allowed 24-hour window.
- 401/403 Authentication Errors: Signal problems with your access token or permissions. Review your Microsoft Entra application setup and token retrieval process.
- 500 Internal Server Error: These are server-side issues. Use retry logic with exponential backoff to handle these temporary errors.
Here's a quick reference for response codes and their meanings:
| Response Code | Meaning | Action Required |
|---|---|---|
| 200 OK | Usage event accepted and recorded | Proceed as normal |
| 400 Bad Request | Invalid data or timing | Verify payload and timing |
| 409 Conflict | Duplicate event | Check for unique event IDs |
| 401/403 | Authentication issues | Refresh token and check permissions |
| 500 | Server error | Retry with exponential backoff |
Always log both successful and failed responses, along with their request and correlation IDs, to aid in troubleshooting and monitoring.
Fixing Common Validation Problems
No matter how carefully you configure your billing API, issues like authentication errors, duplicate events, and data mismatches can crop up. Tackling these problems quickly is essential to maintain accurate billing processes.
Solving Authentication Issues
Authentication problems are often the first roadblock when working with billing APIs. A common error, "InvalidAuthenticationToken", usually points to a configuration mismatch. To address this, ensure your token's audience matches the API endpoint you're calling. Microsoft Support Engineer CarlZhao-MSFT explains:
"This indicates that the API audience of your access token is inconsistent with the API endpoint you are calling" [5].
Double-check settings like Scope, Auth URL, and Access Token URL when generating tokens. Missing the bearer prefix is another frequent issue - always format your header as Authorization: Bearer <access_token>.
For HS256 tokens, ensure your keys are longer than 128 bits. If you're troubleshooting, the Ocp-Apim-Trace-Location header can provide detailed error information. However, as noted by Stack Overflow user szuroszuro:
"Turns out that trace in Azure portal does not display all available information. To be specific: it lacks the on-error entry" [4].
Additionally, confirm that your Microsoft Entra application has the right permissions and that all required claims are included in your token. During testing, leverage Azure API Management's validate-azure-ad-token and validate-jwt policies to enforce proper token validation.
Managing Duplicate Events
Azure's metered billing system enforces a strict one-event-per-hour rule. Submitting more than one usage event per resource and dimension in the same hour triggers a 409 Conflict error, disrupting your workflow. Microsoft's documentation highlights the precision of this rule:
"If you emit a usage event at any time between 8:00 and 8:59:59 (and it is accepted) and send an additional event for the same day between 8:00 and 8:59:59, it will be rejected as a duplicate" [1].
To avoid this, aggregate usage data on your end and implement idempotency logic. Use unique event IDs and timestamps to prevent accidental resubmissions caused by network timeouts or application restarts. When using the batch usage event API, monitor the response status for each event. The API will return a "Duplicate" status code for rejected events, helping you pinpoint and address issues in your batch.
Fixing Data Mismatches
Data discrepancies between your submitted events and Partner Center reports can be frustrating, but they're often traceable with a systematic approach.
First, allow up to 48 hours for Partner Center data to update. If the data still seems off, consider base fee calculations. Azure only bills customers for usage that exceeds any base fees included in their plan. As Microsoft explains:
"You must keep track of the usage in your code and only send usage events to Microsoft for the usage that is above the base fee" [1].
If your submitted events don't exceed the base amount, they won't appear as billable usage in reports.
To verify your data, use the usage events API, which provides detailed status updates for each event. Here's what the key status indicators mean:
| ReconStatus | Description |
|---|---|
| Submitted | Not yet processed by Partner Center Analytics |
| Accepted | Matched with Partner Center Analytics |
| Rejected | Rejected in the pipeline – contact Microsoft support |
| Mismatch | API and Partner Center quantities don't match |
When downloading usage reports, double-check that your subscription IDs, plan IDs, and dimension names match exactly with your API calls. Even small typos or formatting errors can lead to rejected or misclassified events.
If events remain stuck in a "Rejected" status, reach out to Microsoft support with your correlation IDs and request details. These cases often require backend investigation to identify and resolve the root cause.
sbb-itb-cd24f9b
Using WeTransact for API Validation
For small teams, navigating metered billing API validation on Azure Marketplace can feel like an uphill battle. That’s where WeTransact steps in, offering automated tools and streamlined workflows that bring together development, finance, and operations. Here’s a closer look at how WeTransact simplifies each phase of the validation process.
Automated Validation Tools
Gone are the days of manually crafting API calls. WeTransact provides pre-built validation sequences that handle the heavy lifting for you. These tools automatically test billing dimensions, authentication tokens, and event submissions, all while staying compliant with Azure’s one-event-per-hour rule and token formatting requirements.
When issues arise - like incorrect audience settings, missing bearer prefixes, or token permission errors - WeTransact’s tools identify the root cause quickly, saving your team time and frustration.
For teams juggling multiple marketplace offerings, this centralized approach is a game-changer. Instead of managing separate validation scripts for every product, WeTransact consolidates the process, allowing smaller teams to expand their marketplace presence without piling on additional operational work.
Monitoring and Reporting Features
WeTransact’s dashboard provides real-time insights into API validation and billing event processing. It tracks success rates, flags errors, and logs detailed data, making it easier to correlate submitted usage events with Partner Center updates - even when those updates take up to 48 hours to appear. Plus, built-in ROI tracking helps you evaluate financial performance and plan for marketplace growth.
Compliance and Certification Help
Ensuring your metered billing setup aligns with Azure Marketplace certification standards can be overwhelming, but WeTransact simplifies this too. With built-in compliance checklists and guided validation workflows, the platform walks you through the Commercial Marketplace Certification Policies, including SaaS Fulfillment API integration for subscription management. This reduces the risk of launch delays and keeps your certification process on track [6] [7].
Conclusion: Getting Metered Billing Right
Validating metered billing APIs on Azure demands precision and a structured approach. The process hinges on three main pillars: accurate usage tracking, secure communication, and timely event submission. As Microsoft points out:
"You must keep track of the usage in your code and only send usage events to Microsoft for the usage that is above the base fee." [1]
This means ensuring secure HTTPS communication, aggregating usage data hourly, and adhering to the strict 24-hour reporting window for event submissions.
To fine-tune your setup, use a controlled test environment. Configure preview offers with minimal pricing to simulate real-world scenarios and confirm that additional usage correctly triggers billing [1] [3]. These steps not only streamline troubleshooting but also prepare your system for tools like WeTransact.
Platforms such as WeTransact can integrate directly into your testing process, offering automation that simplifies validation. These tools handle tedious tasks like creating manual API calls, provide real-time monitoring to quickly flag issues, and ensure compliance with Azure Marketplace certification standards. By reducing manual work and ensuring everything is aligned, you minimize the risk of delays when launching your metered billing solution.
Ultimately, a well-executed validation process strengthens customer confidence in your billing model. When your APIs work seamlessly from the start, you avoid post-launch headaches and deliver the reliability that enterprise clients expect.
FAQs
How can I test and validate metered billing APIs on Azure without affecting my production environment?
To ensure you can safely test and validate metered billing APIs without affecting your production setup, here are some steps to follow:
- Set up separate Azure subscriptions for testing and production. This keeps resources and permissions completely isolated, minimizing any risk of overlap.
- Implement role-based access control (RBAC) to ensure only authorized developers and testers have access to the test environment. This helps prevent accidental interaction with production resources.
- If using a single subscription, create dedicated resource groups for testing. Clearly label these groups to avoid confusion or unintended changes.
- Perform regular audits and monitoring of access and updates in both testing and production environments. This helps maintain security and ensures compliance with policies.
- Take advantage of Azure Dev/Test subscriptions to reduce costs while keeping your testing environment separate from production.
By keeping your environments isolated and access tightly controlled, you can confidently test your APIs without the risk of disrupting your production systems.
What are common authentication issues with Azure metered billing APIs, and how can I fix them?
Common Authentication Issues with Azure Metered Billing APIs
When setting up Azure metered billing APIs, authentication hiccups often stem from access token problems or incorrect resource identifiers. A common error, such as invalid_resource, typically pops up if the application hasn’t been properly registered in Azure Active Directory or if essential permissions are missing. Another frequent cause is an incorrect Resource parameter in the token request.
To tackle these issues, start by confirming that your application is correctly registered in Azure Active Directory and that all required permissions are in place. Pay close attention to the Resource identifier in your token request - it must align with the expected value for Azure Marketplace APIs. Additionally, take time to review your authentication flow and application settings to catch any misconfigurations that might be causing the problem.
What is the 24-hour reporting window for usage events, and how can I ensure compliance?
The 24-hour reporting window requires that you report usage events within 24 hours of their occurrence. To meet this requirement, ensure your application records usage data precisely and submits events quickly - aiming for submission within an hour of the event. Regularly reviewing and cross-checking your usage data can help maintain its accuracy and strengthen trust with your customers.
Adhering closely to the API specifications is key to avoiding errors or processing delays. Submitting data frequently not only keeps you compliant but also helps your operations run seamlessly and dependably.