Metronome

Automate the usage metering from Metronome to all cloud marketplaces.


Overview

If you currently rely on Metronome as your metering/billing service and are looking to expand your business in cloud marketplaces, Fours offers the ideal solution to bridge the gap. With our no-code, fully automated integration, you can seamlessly meter usages from your existing Metronome instance to clients in all cloud marketplaces. There is no need for migration or extensive engineering efforts, making the process smooth and hassle-free.

Org-Level vs User-Level

Org-Level Only: Metronome integration is available at the organization level only. All users in the organization share the same Metronome connection for usage metering.

When it comes to adopting Fours with Metronome together, you have two options available. However, we highly recommend Option 2, and here’s why:

Option 1Option 2 (recommend)
Architecture
Direct Metronome to AWS Marketplace integration architecture diagram
Integration architecture diagram: the ISV / Seller connects to Metronome, Metronome to Suger, and Suger to the AWS, Azure, and Google Cloud marketplaces
DescriptionMetronome offers officially integrating with AWS Marketplace and sends usage metering to AWS Marketplace metering service directly. Here is the official guidance.Fours provides pre-built integration to connect Metronome & cloud marketplaces. Hourly cron jobs automatically fetch aggregated usage events and report them to cloud marketplace in the right formats.
✅ Pros
  • Officially supported by Metronome.
  • Support all cloud marketplaces (AWS, Azure & GCP).
  • No manual work in Metronome to support private offer in cloud marketplace.
  • Support usage metering verification to avoid overcharge or undercharge.
  • Fully support AutoRenew, Manual Renew / Upsell, Change Plan.
  • Easy configuration, no-code & engineering-free.
🚫 Cons
  • Only AWS Marketplace, GCP or Azure is not supported
  • Require mannual creation of plan & credit in Metronome for each private offer in cloud marketplace.
  • No usage metering verification
  • No support AutoRenew, Manual Renew / Upsell, Change Plan
  • Non-trivial configuration & setup
  • Up to 2 hours delay of reporting usage events to cloud marketplaces

How the sync works

DirectionOne-way: Metronome → Fours → cloud marketplace. Fours reads usage and invoices from Metronome and reports them onward as usage record groups. Fours never writes back to Metronome.
Source of truthMetronome owns usage and invoice amounts. Fours owns the mapping to marketplace dimensions and the reported records.
ScopeOrganization-level only — one Metronome connection per Fours organization, shared by all users.
ScheduleAn hourly job at 35 minutes past the hour, when Enable Auto Report Usage is on and the integration is VERIFIED. In amount_daily billing mode the amount is reported daily rather than hourly.
CredentialsA Metronome API token, sent as a bearer token. Fours stores it in a secret manager, not in the integration record, and deleting the integration deletes it immediately and permanently. Give the token access to the invoice and usage endpoints Fours reads — Metronome’s authentication guide covers issuing one.

When something fails

  • One bad buyer or invoice does not stop the run, but it does fail it. Fours reports each buyer separately and continues to the next buyer and the next invoice, so a single unmappable record cannot block every other customer’s usage for that hour. Once every buyer has been tried, a run in which any buyer’s usage couldn’t be reported ends as failed, and its reason says how many buyers were affected — see Troubleshoot a failed sync.
  • Fixed-fee entitlements are left out. A fixed-fee entitlement has no usage pricing, so Fours never reports Metronome usage to it. A buyer whose entitlements are all fixed-fee is skipped and doesn’t fail the run; a buyer that also has a usage entitlement has its usage reported to that one.
  • Transient failures are retried automatically — every read Fours makes from Metronome (usage, invoices, billable metrics, and the connection test behind VERIFY) is retried up to twice, a few seconds apart, when it is rate-limited, times out, or gets a Metronome server error. In the hourly usage sync, a buyer counts as failed only after those retries; the per-organization sync retries after a 10-second delay, and the run has a 60-minute ceiling. A run that failed because of its buyers is not retried within the hour: the next hourly run is the retry.
  • A failed hour is not skipped forever. The job re-reads current usage and invoice state on its next pass, so a recovered outage catches up on the following run rather than needing a manual backfill.
  • Duplicate reporting is guarded by amount history, not by retry count. In amount_hourly and amount_daily modes Fours tracks the highest invoice total it has already reported per Metronome invoice ID and only reports increases — so a retried or repeated run does not double-charge.

Create Integration

In your Fours Console Integration, you will see the Metronome integration connection. Click the Connect button to create an integration with your Metronome instance. This will open an dialog for you to input

  • API Token: The Metronome API token.
  • Billing Mode: Select one of quantity, amount_hourly or amount_daily. See Billing Mode for the difference between them.
Metronome integration dialog with API Token and Billing Mode fields

Once the integration process is finished, you can proceed by clicking the VERIFY button. This action triggers the Fours service to test the connection to the APIs of your Metronome instance. If everything is configured correctly, the integration status will be updated as VERIFIED.

Edit Integration

Editing an existing Metronome integration is supported. Click the Edit button to open the dialog of editing Metronome integration as shown below.

  • Enable Auto Report Usage. You can choose to enable or disable the automatic usage report feature for Metronome. Enabling this feature allows Fours to run an hourly cron job to retrieve the aggregated usage events from Metronome and report them as UsageRecordGroups to the Fours metering API. On the other hand, disabling this feature means that no cron job will be scheduled for this purpose.

  • Billing Mode: quantity, amount_hourly or amount_daily. See Billing Mode for the difference between them.

    Following features are available when the billing mode is amount_hourly or amount_daily:

    • Enable Report Finalized Invoice Only: If enabled, Fours will only report finalized invoices to cloud marketplaces. By default, Fours will also report draft invoices to cloud marketplaces.

    • Enable Invoice End Date Check: If enabled, Fours will check the end date of an invoice the first time it reports it. If the end date is not in the entitlement time window, Fours will not report the usage to cloud marketplaces. An invoice already reported stays with its entitlement. When several of a buyer’s entitlements can take the invoice amount, Fours routes each invoice by its end date whether or not this is on — see Which entitlement an invoice is reported to.

    • Enable Auto Credit Back for Voided Invoices: If enabled, Fours will automatically add reported amount of voided invoices to the entitlement as credit. By default, Fours will not add the voided invoices to the entitlement as credit.

    • Enable Invoice Filter: If enabled, a JavaScript filter you supply decides which invoices Fours ingests. Leave it off to ingest every invoice that passes the other checks above.

    • Invoice Filter Code: Applicable only when Enable Invoice Filter is on. Your code receives $invoices (the array of invoice objects fetched from Metronome) and must set $target.invoiceIds to the IDs it wants to keep. For example, to ingest only invoices a Metronome custom field has not opted out:

      const invoiceIds = [];
      for (const invoice of $invoices) {
        if (invoice.custom_fields && invoice.custom_fields.suger_ingest_invoice !== 'false') {
          invoiceIds.push(invoice.id);
        }
      }
      $target.invoiceIds = invoiceIds;
  • Allow Zero Usage Record Group. By default Fours skips creating a usage record group when a sync produces no usage. Enable this to create the zero-record group anyway — it is still not reported to the cloud marketplace, but it makes “we synced and there was genuinely no usage” distinguishable from “the sync did not run”.

    Metronome Integration Amount Options

  • Enable Billable Metric Whitelist. Shown only when Billing Mode is quantity. If enabled, only the billable metrics in the whitelist will be metered & reported from Metronome to cloud marketplaces. Otherwise all the metrics listed in the Billable Metric Full List will be metered & reported to cloud marketplaces.

  • Billable Metric Whitelist. Applicable only when the Enable Billable Metric Whitelist is true.

  • Billable Metric Full List. Shown only when Billing Mode is quantity. Every non-archived billable metric in your Metronome account. It is auto fetched from Metronome, not editable, and Fours refreshes it only while the billing mode is quantity.

    In amount_hourly and amount_daily the dialog hides these three fields, because those modes report invoice totals rather than billable metrics. A whitelist you saved earlier is kept, and applies again if you switch back to quantity.

Edit Metronome integration dialog with billing and metric options

Delete Integration

The Metronome integration can be deleted like all other integrations. Once the deletion is triggered, all integration info including the API token will be deleted immediately & permanently from Fours. No time window or methods to recover.

Billing Mode

There are three billing modes available for Fours-Metronome integration: quantity, amount_hourly or amount_daily.

  1. quantity: Fours fetch & report the billable metrics by quantity every one HOUR. Use the original Metronome billable metrics as the source dimension keys in the configuration of metering dimension conversion

  2. amount_hourly: Fours fetch & report invoice total amount every one HOUR. The invoice total amount is converted to the dimension metronome with fixed unit price as $1. Use metronome as the only source dimension key in the configuration of metering dimension conversion.

  3. amount_daily: Fours fetch & report the invoice total amount every one DAY. The total amount is converted to the dimension metronome with fixed unit price as $1. Use metronome as the only source dimension key in the configuration of metering dimension conversion.

Which entitlement an invoice is reported to

In amount_hourly and amount_daily, every invoice amount goes out on the metronome key, so Fours reports it only to an entitlement that can take that key: one with a dimension keyed or named metronome; one with the dimension metronome is mapped to, with Enable Dimension Mapping turned on for that marketplace in Metering Dimension Conversion; or an Oracle entitlement still under Fours’ limit of 100 usage keys. Fixed-fee entitlements are never used.

  • None of the buyer’s entitlements can take it: the buyer fails before anything is reported.
  • One can: its invoices go to that entitlement. An invoice Fours has already reported stays with it; with Enable Invoice End Date Check on, an invoice being reported for the first time is skipped if its end date falls outside the entitlement’s term.
  • Several can: each invoice goes to the one whose term covers the invoice’s end date, whatever Enable Invoice End Date Check says. Both ends of a term count, and where one term ends as the next begins, the newer term takes the invoice — so a renewal works. An invoice Fours has already reported keeps the entitlement it went to. An invoice that none of them covers is skipped.
  • More than one covers the same invoice: the buyer has concurrent agreements, which Fours does not support. That invoice is not reported, and the buyer fails.

Troubleshoot a failed sync

Fours reports each buyer separately, so one buyer’s problem doesn’t stop the others, but any buyer whose usage can’t be reported makes the run end as failed. Open Operations from the Metronome card’s ⋯ menu in Settings → Integration, then hover the run’s Failed status to read why, or click its View details icon. The reason gives a count, for example Metronome usage wasn’t reported for 2 of 9 buyers. Contact Fours support for more details. A run that fails for any other reason reads Internal error. Contact Fours support for more details. The console doesn’t list the buyers or what went wrong for each: Fours keeps that in its logs, so contact Fours support to find out which buyers failed and why. The table below lists the common causes and the fix for each.

Common causeWhat to do
The entitlement doesn’t have some usage dimensions, so some hours weren’t reported (quantity mode)Add the missing dimensions to the offer as usage dimensions, then ask Fours support to add them to the entitlement. If they aren’t sold through the marketplace, turn on Enable Billable Metric Whitelist on the integration and leave them off the whitelist. On an Oracle entitlement the same cause means the new keys would take it past 100 usage keys: ask Fours support to remove the entitlement’s unused usage dimensions, or leave the metrics off the whitelist.
None of the buyer’s entitlements can take the metronome amount, so its invoice amounts weren’t reported (amount_hourly and amount_daily modes)Add the usage dimension that metronome is mapped to in Metering Dimension Conversion to the offer, then ask Fours support to add that dimension to the entitlement.
More than one of the buyer’s entitlements covers the same invoice — concurrent agreements (amount_hourly and amount_daily modes)Fours reports each invoice to a single entitlement, so that invoice wasn’t reported. See the warning at the top of this page.
The integration has no supported billing modeChoose a billing mode in the integration’s Edit dialog (see Billing Mode).
Metronome rejected the API tokenConnect Metronome again with a valid token. The edit dialog has no API token field, so delete the integration, create it again, and set its options again.
Metronome rate-limited the requests, or Metronome was unavailableNothing — the next sync tries again.
An internal errorThe next sync tries again. Contact Fours support if it keeps failing.

Usage Fours leaves out on purpose doesn’t fail a buyer: usage it has already reported, a zero invoice amount, a fixed-fee entitlement, an invoice that none of the buyer’s entitlements covers, and — with Enable Invoice End Date Check on — an invoice whose end date falls outside the entitlement’s time window when Fours would first report it.

Spotted something wrong or out of date on this page? Tell us and we'll correct it.