Skip to main content
Connector ID 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

With ingestion 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, body next_page, or body cursor as 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-After when supplied. Metronome reports whether a throttle applies to the client or customer through X-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.