How to manage Vendor meters via API

Introduction

This article explains how to manage Vendor Meters through the Platform API when working with usage-based pricing. It covers how to retrieve existing Vendor Meters, create a new Meter when one does not exist, and add Meter pricing variables to a Pricing Plan — all through API calls instead of the user interface.

Meters and their pricing variables are managed separately from the Pricing Plan itself through dedicated API endpoints. The usagePricing property is not saved as part of the Pricing Plan creation or update request. Instead, Meter definitions and their pricing are handled through the Metering API.

 To learn how to manage Vendor Meters through the user interface, see "How to create and reuse Vendor Meters in Pricing Plans".

In this article:

• Before you begin
• Step 1: Retrieve the Vendor Meter list
• Step 2: Create a new Vendor Meter (if needed)
• Step 3: Add a Meter Variable to the Pricing Plan
• Important information
• Summary

Before you begin

Meters and their pricing variables are managed separately from the Pricing Plan. To configure usage-based pricing, first create the Pricing Plan as before using the Create Pricing Plan API. Once the Pricing Plan has been created, use the dedicated API endpoints to create and manage its usage meters and pricing variables.

To complete this flow you need:

• An active API subscription key (Ocp-Apim-Subscription-Key)
• A valid Bearer Token for authorization
• The Api-Version header (for example, 2021-04-01)
• The vendorId of the Vendor whose Meters you want to manage
• The offerId and effectiveFromDate of the Offer and Pricing Plan you are configuring

The three API endpoints used in this flow are:

Base URL: https://api.appxite.com/producthub

Step 1: Retrieve the Vendor Meter list

Before adding a Meter to the Pricing Plan, check whether it already exists for this Vendor. Each Vendor Meter is stored once and can be reused across all of that Vendor's Offers and Pricing Plans — including plans in a different currency, since a Meter definition is currency-agnostic.

Request

GET https://api.appxite.com/producthub/api/Meters/by-vendor/{vendorId} — View in Developer Portal

Request parameters

Request headers

Response: 200 OK

The response returns an array of all Meters that exist for this Vendor.

[
  {
    "id": "60d751e9-92a1-417c-9a3c-a63c2cdff857",
    "vendorId": "b8dcb722-4ef4-4365-ba95-a2ad4ccf7bb4",
    "idFromVendor": "ax-test-bandwidth-01",
    "name": "Bandwidth",
    "category": "Bandwidth",
    "subCategory": "Bandwidth",
    "unit": "Bandwidth",
    "marketplaceMappings": {},
    "aggregationType": "Sum",
    "status": "Active",
    "createdAt": "2026-09-23T10:57:00.9992",
    "updatedAt": "2026-09-23T10:57:00.9992"
  }
]

What to do next

• Search the response for a record where idFromVendor matches the Meter you want to add. The idFromVendor value is trimmed and lower-cased on write, so VM-CPU-Hours and vm-cpu-hours are treated as the same Meter.
• If you find a matching Meter, note its id value — this is the internal identifier you need in Step 3. Skip ahead to Step 3.
• If no matching Meter exists, continue with Step 2 to create one.

Step 2: Create a new Vendor Meter (if needed)

If the Meter you need does not exist in the response from Step 1, create it. Once created, the Meter is stored for the Vendor and becomes available to add in any of that Vendor's Pricing Plans — including plans in a different currency, since a Meter definition is currency-agnostic.

Request

POST https://api.appxite.com/producthub/api/Meters — View in Developer Portal

Request headers

Request body

{
  "idFromVendor": "ax-test-storage-01",
  "vendorId": "b8dcb722-4ef4-4365-ba95-a2ad4ccf7bb4",
  "name": "Storage",
  "category": "Storage",
  "subCategory": "Storage",
  "unit": "Storage"
}

Request body fields

Response: 200 OK

The response returns the created Meter, including its system-generated id. Store this id — you need it in Step 3.

{
  "id": "158b9b69-da8a-4a97-aa85-56993a66294b",
  "idFromVendor": "ax-test-storage-01",
  "vendorId": "b8dcb722-4ef4-4365-ba95-a2ad4ccf7bb4",
  "name": "Storage",
  "category": "Storage",
  "subCategory": "Storage",
  "unit": "Storage",
  "createdAt": "2026-10-28T07:31:10.30233612",
  "updatedAt": "2026-10-28T07:31:10.30233612"
}

Response: 409 Conflict

If a Meter with the same idFromVendor already exists for this Vendor, the API returns a 409 Conflict response:

A meter with the same IdFromVendor already exists for this vendor.

In this case, go back to Step 1 and use the existing Meter instead.

Step 3: Add a Meter Variable to the Pricing Plan

Once you have the Meter id (from Step 1 or Step 2), add its pricing to the Pricing Plan by creating a Meter Variable. A Meter Variable defines the pricing formula, tiers and rate for one Meter within one specific Pricing Plan version.

Request

POST https://api.appxite.com/producthub/api/MeterVariables — View in Developer Portal

Request headers

Request body

{
  "meterId": "158b9b69-da8a-4a97-aa85-56993a66294b",
  "groupKey": {
    "vendorId": "b8dcb722-4ef4-4365-ba95-a2ad4ccf7bb4",
    "offerId": "fb33dc87-ec18-4c64-ae75-a2b3fae17f49",
    "effectiveFromDate": "2026-10-28"
  },
  "key": {
    "currencyCode": "EUR",
    "countryCode": "ALL"
  },
  "variables": [
    {
      "variableName": "Price",
      "billingCycle": "Monthly",
      "title": {
        "en-US": "Price"
      },
      "formulaLines": [
        {
          "operator": "Equals",
          "function": {
            "functionType": "QuantityPriceTable",
            "quantityProvider": {
              "meterId": "158b9b69-da8a-4a97-aa85-56993a66294b",
              "providerType": "UseMeter"
            },
            "includedQuantity": 0,
            "tierMode": "Volume",
            "rows": [
              {
                "minQuantity": 1,
                "maxQuantity": 1000,
                "inPrice": 1,
                "retailPrice": 2
              }
            ]
          }
        }
      ]
    }
  ]
}

Key fields in the request body

Response: 200 OK

The response returns the created Meter Variable with its own id, along with timestamps.

{
  "id": "7ae1a378655dcda77f74b3ed",
  "meterId": "158b9b69-da8a-4a97-aa85-56993a66294b",
  "groupKey": {
    "vendorId": "b8dcb722-4ef4-4365-ba95-a2ad4ccf7bb4",
    "offerId": "fb33dc87-ec18-4c64-ae75-a2b3fae17f49",
    "effectiveFromDate": "2026-10-28"
  },
  "key": {
    "currencyCode": "EUR",
    "countryCode": "ALL"
  },
  "variables": [
    {
      "variableName": "Price",
      "apiParameterName": null,
      "billingCycle": "Monthly",
      "formulaLines": [
        {
          "operator": "Equals",
          "function": {
            "functionType": "QuantityPriceTable",
            "quantityProvider": {
              "providerType": "UseMeter",
              "meterId": "158b9b69-da8a-4a97-aa85-56993a66294b"
            },
            "includedQuantity": 0,
            "tierMode": "Volume",
            "rows": [
              {
                "minQuantity": 1,
                "maxQuantity": 1000,
                "inPrice": 1,
                "retailPrice": 2
              }
            ]
          }
        }
      ],
      "title": {
        "en-US": "Price"
      }
    }
  ],
  "createdAt": "2026-10-28T07:24:56.17785682",
  "updatedAt": "2026-10-28T07:24:56.17791162"
}

After this step the usage pricing is associated with the Pricing Plan. When the Pricing Plan is read back through the API, the usagePricing.meters section is automatically populated from the Metering API.

Important information

• The usagePricing property is accepted but not saved when included in the Create Pricing Plan request. It is still validated: if usagePricing.meters is present and contains invalid data (for example, a missing meterId or an invalid variable), the request returns a 400 error and the Pricing Plan is not saved — even though the Meters would not have been stored.
• The idFromVendor value is trimmed and lower-cased on write. For example, VM-CPU-Hours and vm-cpu-hours are treated as the same Meter. Attempting to create a duplicate returns a 409 Conflict error.
• The effectiveFromDate in the Meter Variable request must match the Pricing Plan's groupKey.effectiveFromDate exactly.
• The countryCode defaults to ALL when a Pricing Plan has no country-specific configuration.
• The meterId at the top level of the Meter Variable request body must match the meterId inside variables[].formulaLines[].function.quantityProvider.meterId. If these values do not match, usage pricing does not work as expected.
• Supported aggregationType values are: Sum, Max, Avg, Count. Supported status values are: Active, Deprecated, Deactivated.
• Supported functionType values for pricing formulas are: Constant, PerUsage, QuantityPriceTable, QuantityInterpolation, ChoicePriceTable.
• A quantityProvider can be either UseMeter (references a Meter by its meterId) or UseQuantityControl (references a Pricing Plan control by its controlId). For usage-based pricing, use UseMeter.
• JSON is camelCase; enum values are sent as strings (for example, "Sum", "Monthly", "PerUsage").
• An open-ended maxQuantity in a pricing tier row is represented as the string "+∞".
• A Meter cannot be deleted while any Pricing Plan still references it. Remove the Meter from all referencing Pricing Plans before deleting.
• If you need help resolving a duplicate Meter error or removing a Meter that appears stuck, submit a Support request.

Summary

Usage-based Meter pricing is managed through three dedicated API endpoints. Retrieve the Vendor's existing Meters to check whether the Meter you need already exists. If not, create a new Vendor Meter. Then add a Meter Variable to the Pricing Plan to define the pricing formula, tiers and rate for that Meter.

The usagePricing.meters data is automatically included in the response when you read a Pricing Plan back through the API — the Platform fetches it from the Metering API at read time. This ensures that Pricing Plan consumers such as the marketplace, price calculation and estimate services see the correct usage pricing without any additional steps.

Related content

• How to add a Vendor Meter to a pricing plan
• Developer Portal — Product Hub API