# Metronome
Automate the usage metering from Metronome to all cloud marketplaces.
---
## Overview
If you currently rely on [Metronome](https://metronome.com/) 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.
:::warning
This integration does not currently disambiguate between a buyer's [AWS Concurrent Agreements](/aws-marketplace/integration/#enable-concurrent-agreements) for the same product — usage can be attributed to the wrong agreement. If your product has Concurrent Agreements enabled, report usage through Fours directly instead. See [Usage Metering for AWS Concurrent Agreements](/metering/usage-metering/#usage-metering-for-aws-concurrent-agreements).
:::
### 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 1 | Option 2 (recommend) |
| ----------- | ----------- | ------------ |
| Architecture |
| 
|
| Description | Metronome offers officially integrating with AWS Marketplace and sends usage metering to AWS Marketplace metering service directly. Here is the [official guidance](https://docs.metronome.com/integrations/marketplace-integrations/aws). | 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. |
| :white_check_mark: 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.
|
| :no_entry_sign: 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
| | |
| --- | --- |
| **Direction** | One-way: Metronome → Fours → cloud marketplace. Fours reads usage and invoices from Metronome and reports them onward as [usage record groups](/metering/usage-metering/). Fours never writes back to Metronome. |
| **Source of truth** | Metronome owns usage and invoice amounts. Fours owns the mapping to marketplace dimensions and the reported records. |
| **Scope** | Organization-level only — one Metronome connection per Fours organization, shared by all users. |
| **Schedule** | An 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. |
| **Credentials** | A 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](https://docs.metronome.com/api-reference/authentication) covers issuing one. |
### When something fails
- **One bad buyer or invoice does not stop the run.** The sync logs the failure 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.
- **Transient failures are retried automatically** — the per-organization sync retries after a 10-second delay, and the run has a 60-minute ceiling.
- **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](https://console.suger.io/settings?tab=integrations), 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](https://docs.metronome.com/api-reference/authentication).
- **Billing Mode**: Select one of `quantity`, `amount_hourly` or `amount_daily`. See [Billing Mode](#billing-mode) for the difference between them.
> 
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](/metering/usage-metering/). 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](#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 the invoice. If the `end date` is not in the entitlement time window, Fours will not report the usage to cloud marketplaces.
- **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:
```javascript
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".
> 
:::warning
- Fours only sync invoices with billing periods that **begin on or after the first day of the previous month**. Any billing periods that start before this date will not be reported to cloud marketplaces.
- If the **start date** of the invoice is in the future, Fours will not report the usage to cloud marketplaces.
- **Enable Billable Metric Whitelist**. 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**. The full list of billable metrics fetched from Metronome for all available Metronome customers. It is auto fetched from Metronome, not editable.
:::warning
- If the billing mode is `quantity`, please ensure all billable metrics in the `Whitelist` (if the whitelist is enabled) or the `Full List` (if the whitelist is not enabled) have been mapped to their respective cloud marketplace dimensions in the [Metering Dimension Conversion](/metering/usage-metering/#metering-dimension-conversion).
- Metronome Auto Fetch & Report Job: In case any billable metrics from Metronome cannot be successfully converted to metering dimensions in the cloud marketplace, it may result in the entire Metronome auto fetch and report job failing.
- If you notice any discrepancies or missing usage reporting, please verify whether this is caused by incomplete mapping of billable metrics to cloud marketplace dimensions. If so, rectify the mapping accordingly to ensure accurate reporting.
:::
> 
## 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](/metering/usage-metering/#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](/metering/usage-metering/#metering-dimension-conversion).
:::tip
- Fours fetches [Metronome Invoice API](https://docs.metronome.com/api/#operation/listInvoices) every one hour. If there is an increase in the `invoice total amount`, Fours will generate a new usage record and report it to cloud marketplaces. However, if the `invoice total amount` remains the same or decreases, Fours will refrain from creating new usage records..
- In cases where credits are granted to the customer in Metronome, resulting in a potential decrease in the `invoice total amount`, Fours retains a comprehensive history of invoice total amounts and monitors any changes. If the `invoice total amount` decreases or remains unchanged, Fours will suspend the automatic fetching and reporting of usage until it surpasses the maximum value recorded in its history.
:::
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](/metering/usage-metering/#metering-dimension-conversion).
:::warning
When using the `amount_hourly` or `amount_daily` billing modes, pay attentions to the following:
- Fours tracks each invoice amount using the Metronome `invoice ID` and reports increases to the cloud marketplace on an hourly or daily basis. If a customer’s contract is modified or an operation changes the `invoice ID`, Fours will start reporting amounts based on the new invoice ID. This can lead to a sudden spike in the usage report.
- To avoid this, **schedule contract changes or similar operations to take effect at the beginning of the month**. This approach minimizes disruptions and ensures a smoother and more consistent usage reporting process.
:::