metronome
The Metronome source provides 46 selectable resources through an
HTTP manifest.
It targets Contracts v2 with the shared v1 endpoints and optional legacy Plans
reads. Use metronome@v2 to pin this API selection. metronome resolves to it.
The connector is in preview. Its API contracts and shared engine have been
checked locally, but live account reads have not been validated.
Configuration
Dates use
YYYY-MM-DD and are sent at UTC midnight. Windowed resources require
both start_date and end_date. Other resources do not require a date window.
Create a token under Developer → API tokens in the Metronome app. Tokens
inherit their creator’s permissions unless Metronome applies narrower access.
Use a read-only token for the intended environment and grant access to each
selected endpoint, including POST reads. See
API authentication.
Connection testing reads one billable-metrics page and requires access to that
endpoint. Discovery alone does not test access.
Resources
The default selection includes billable metrics, customers, products, rate cards, pricing units, custom field keys, account billing providers, customer billing configurations, contracts, commits, credits, packages, and invoices. All other resources are opt-in.Customers and reference data
Contracts, commitments, and packages
Invoices, usage, and rates
Notifications
Administration
Account-specific features
Legacy Plans and amendments
Each list emits one row per returned object. Related line items, ledgers,
contract terms, subscription schedules, package terms, and notification policies
remain JSON arrays or objects. IDs remain strings,
amounts and fractional quantities use decimal projections, and timestamps carry
time zones. Every resource includes a
raw remainder for additional fields.
Contract responses can truncate embedded commits and credits. Use commits and
credits for their complete paginated lists, including contract-level and archived
records with ledgers and balances. balances provides the combined view.
seat_balances includes all returned seats with their credits, commits, and ledgers.
See list customer contracts
and list seat balances.
subscriptions reads the subscription array from each contract detail. Quantity
history includes past changes, while future quantity schedules remain on the
subscription. Seat history returns schedule segments and assigned seat IDs.
net_balances queries each customer and pricing unit separately, including custom
units. net_quantity_balances queries quantity-based balances separately. These
are current snapshots and include draft invoice deductions under the API default.
usage reads daily aggregates for all customers and metrics in the selected
window without requesting truncated inline groupings. Rate card schedules include
every past and future segment. Contract rates reflect the schedule in effect when
the read runs. Invoice breakdowns emit daily windows. Spend breakdowns use the
API’s default presentation groups.
Approval requests, revenue system configurations, historical balances, spend
breakdowns, and named schedules come from the
official OpenAPI specification.
These include feature-gated and private-preview APIs. Enable only resources your
account supports. Contract named schedules use the listing endpoint and retain
property-qualified schedules and all segments.
Legacy Plans resources are optional for accounts that still use that deprecated
product. legacy_contracts retains the v1 initial, current, and amendment views.
plan_details adds minimums, overage rates, and plan credit-grant definitions.
plan_customers includes past, current, and upcoming assignments. Legacy grants
and ledgers exclude voided grants upstream. Legacy costs do not support plans
with UNIQUE billable metrics. See the
legacy Plans reference.
Coverage boundaries
The resource set reconciles the published Contracts and legacy Plans indexes with the official OpenAPI read operations. Individual lookups for customers, billable metrics, products, rate cards, invoices, packages, approval requests, contracts, offset notifications, and contract named schedules repeat data available through the included lists. Threshold-notification lists include customer evaluation status and configuration. Filtered point-in-time lookup variants are not separate resources. Audit logs, invoice PDF downloads, and generated embeddable dashboard URLs are not replicated. Write operations, invoice simulations, webhook reception, and endpoints without published request and response contracts are outside this source. Lookups that need IDs or names the API cannot list are not replicated. These cover event search by transaction ID, webhook delivery history, usage by a single grouping key, customer and rate card named schedules, and point-in-time rate lookups. The API offers no raw-event listing. For raw events and large accounts, use Metronome’s data export to a warehouse or object store.Webhooks
Withingestion set to webhooks or both, the connection offers two
resources that hold the notifications Metronome pushes to a
webhook destination.
A webhooks connection needs no API token and offers only these resources.
With both, one pipeline can hold them and API resources together. Its schedule and
Run read the API resources, and Start stream reads the webhook
resources continuously. Webhooks also need the server settings described in
the webhook source.
Metronome creates the signing secret only after it has the delivery URL, and
the URL exists only once the connection does. After you create the connection,
Filament shows its delivery URL. In Metronome, open Developer → Notifications
→ Webhooks, choose Add and set that URL. Copy the secret Metronome shows
into Signing key and save it. To finish later, choose Set up later
and then Add in the connection’s Secrets section. Filament does not
generate a secret for Metronome. One destination receives every notification
type, and Filament routes each one by its type. Each Metronome webhook has
its own secret and a connection verifies one, so point one webhook at each
connection. Sandbox and production need separate connections.
Metronome signs each request with HMAC-SHA256 over X-Metronome-Date and the
body. Filament rejects a request whose signature does not verify or whose date
is more than five minutes from the server’s clock. The payload id names one
triggered notification and stays the same on every delivery attempt, so a
retried notification is stored once.
system_notifications_webhook columns are id, type, timestamp,
environment_type, customer_id, contract_id, commit_id, credit_id,
subscription_id, invoice_id, invoice_type, segment_id, offset_id,
offset_duration, customer_custom_fields and contract_custom_fields. An
offset notification carries its policy’s type plus offset_id and
offset_duration. notifications_webhook columns are id, type, and
customer_id, alert_id, invoice_id and timestamp from properties, with
the whole properties object as JSON. Both end with raw, the fields the
manifest does not project.
A system or offset type Metronome adds later reaches notifications_webhook
with its fields in raw. Delivery is at least once, so upsert or merge on id
keeps one row per notification. Notifications are minimal. Join on their IDs to
the API resources for full records. Some types need Metronome to enable them,
such as invoice.finalized. A delivery whose body does not match its resource
is skipped and counted, as the webhook source
describes.
Modes
All resources use full reads. Creation dates, usage windows, and effective dates do not establish update-watermark semantics for mutable billing records. Repeated full reads refresh edited invoices, balances, ledgers, and contracts. Windowed reads cover only the configured interval. Use full replace for keyless resources. These include rate rows, usage aggregates, invoice breakdowns, seat-history segments, threshold and system notifications, named schedules, plan assignments and adjustments, legacy ledger batches, and legacy daily costs. Their upstream rows do not expose a suitable stable row ID. Other resources support upsert by the declared ID or parent-scoped key. Full upsert does not remove absent records. Full replace can reflect removals only within the selected visibility, interval, and upstream retention.Behavior
- Auth uses bearer authentication against
https://api.metronome.com. - Pagination follows URL
next_page, bodynext_page, or bodycursoras specified by each endpoint. Null cursors end a read. General listings request 50 rows, contracts request 20, commitment lists request 25, and seat history requests 10. Short pages do not end a read while a continuation cursor exists. - System notifications use the documented single-request endpoint. Its schema contains a nullable cursor but documents no continuation parameter. A nonempty cursor fails the read instead of silently dropping more data. Such a response requires upstream clarification of the continuation contract.
- Parents are fetched for selected child resources even when the parent is not selected for output. Customer reads walk active and archived lists by default. Products, packages, contracts, commitments, billing configurations, and threshold notifications explicitly request archived data where supported. Other listings retain upstream visibility defaults.
- Recovery restarts child reads and configured lookup loops. Ordinary top-level cursor reads can resume saved pagination state. These checkpoints are not update-based incremental replication.
- Rate limits use the shared HTTP retry handling for 429 responses and server
errors, honoring
Retry-Afterwhen supplied. Metronome reports whether a throttle applies to the client or customer throughX-Metronome-Rate-Limit-Type. See API status codes. - Errors remain visible. Missing permissions and unavailable account features are not converted into empty data.
- Consistency follows the upstream reads. Requests across customers and API families do not form an atomic billing snapshot. Archived status can change while active and archived customer passes are running.