Metronome User Management API Guide

Auth method: Bearer token (API key)

Setup steps

1. Log in to the Metronome dashboard.
2. Navigate to Settings > API Keys.
3. Generate a new API key.
4. Include the key in the Authorization header as: Authorization: Bearer

Create customer

• Method: POST
• URL: https://api.metronome.com/v1/customers
• Watch out for: ingest_aliases must be globally unique; duplicate aliases will cause event ingestion conflicts.

Request example

POST /v1/customers
Authorization: Bearer <API_KEY>
Content-Type: application/json
{
  "name": "Acme Corp",
  "ingest_aliases": ["acme-corp-001"]
}

Response example

{
  "data": {
    "id": "3a1b2c3d-...",
    "name": "Acme Corp",
    "ingest_aliases": ["acme-corp-001"],
    "created_at": "2024-01-15T10:00:00Z"
  }
}

List customers

• Method: GET
• URL: https://api.metronome.com/v1/customers
• Watch out for: Use next_page cursor token for pagination; absence of next_page indicates last page.

Request example

GET /v1/customers?limit=100
Authorization: Bearer <API_KEY>

Response example

{
  "data": [{"id": "...", "name": "Acme Corp"}],
  "next_page": "eyJpZCI6..."
}

Get customer

• Method: GET
• URL: https://api.metronome.com/v1/customers/{customer_id}

Request example

GET /v1/customers/3a1b2c3d-...
Authorization: Bearer <API_KEY>

Response example

{
  "data": {
    "id": "3a1b2c3d-...",
    "name": "Acme Corp",
    "ingest_aliases": ["acme-corp-001"]
  }
}

Update customer

• Method: POST
• URL: https://api.metronome.com/v1/customers/{customer_id}
• Watch out for: Metronome uses POST (not PATCH) for customer updates on some endpoints; verify against current API reference.

Request example

POST /v1/customers/3a1b2c3d-...
Authorization: Bearer <API_KEY>
Content-Type: application/json
{
  "name": "Acme Corp Updated"
}

Response example

{
  "data": {
    "id": "3a1b2c3d-...",
    "name": "Acme Corp Updated"
  }
}

Set customer billing config

• Method: POST
• URL: https://api.metronome.com/v1/customers/{customer_id}/setBillingConfig
• Watch out for: Billing provider must be configured in Metronome dashboard before this call succeeds.

Request example

POST /v1/customers/3a1b2c3d-.../setBillingConfig
Authorization: Bearer <API_KEY>
Content-Type: application/json
{
  "billing_provider_type": "stripe",
  "billing_provider_customer_id": "cus_abc123"
}

Response example

{}

Archive customer

• Method: POST
• URL: https://api.metronome.com/v1/customers/{customer_id}/archive
• Watch out for: Archiving is irreversible via API; archived customers cannot be reactivated through standard endpoints.

Request example

POST /v1/customers/3a1b2c3d-.../archive
Authorization: Bearer <API_KEY>

Response example

{}

List customer plans

• Method: GET
• URL: https://api.metronome.com/v1/customers/{customer_id}/plans

Request example

GET /v1/customers/3a1b2c3d-.../plans
Authorization: Bearer <API_KEY>

Response example

{
  "data": [{"id": "...", "plan_name": "Pro", "starting_on": "2024-01-01"}]
}

Add plan to customer

• Method: POST
• URL: https://api.metronome.com/v1/customers/{customer_id}/plans/add
• Watch out for: starting_on must be a future date aligned to billing period boundaries; misaligned dates may cause billing errors.

Request example

POST /v1/customers/3a1b2c3d-.../plans/add
Authorization: Bearer <API_KEY>
Content-Type: application/json
{
  "plan_id": "plan-uuid-...",
  "starting_on": "2024-02-01T00:00:00Z"
}

Response example

{
  "data": {
    "customer_plan_id": "cp-uuid-..."
  }
}

• Rate limits: Metronome does not publicly document specific rate limit thresholds or tiers in their official docs as of the research date.

• Rate-limit headers: Unknown

• Retry-After header: Unknown

• Rate-limit notes: No publicly documented rate limits found. Contact Metronome support for enterprise rate limit details.

• Pagination method: cursor

• Default page size: 100

• Max page size: Not documented

• Pagination pointer: next_page

• Webhooks available: Yes

• Webhook notes: Metronome supports webhooks for event-driven notifications on billing and usage events.

• Alternative event strategy: Not documented

• Webhook events: invoice.finalized, invoice.payment_failed, customer.plan.added, customer.plan.ended, alert.triggered

• SCIM available: No
• SCIM version: Not documented
• Plan required: Not documented
• Endpoint: Not documented

Limitations:

• No SCIM provisioning support documented in official Metronome docs.
• No IdP integrations (Okta, Entra, Google Workspace, OneLogin) documented for SCIM.

Three primary automation scenarios are supported by the documented endpoints.

First, provisioning a new billing customer: POST /v1/customers with name and ingest_aliases, capture the returned id, call setBillingConfig to attach a Stripe customer ID, then POST to /v1/customers/{customer_id}/plans/add with a future starting_on date aligned to billing period boundaries

misaligned dates risk billing errors.

Second, paginating all customers: GET /v1/customers?limit=100, follow the opaque next_page cursor token until it is absent;

cursor tokens are time-sensitive and must not be cached across sessions.

Third, archiving a churned customer: confirm no active plans via GET /v1/customers/{customer_id}/plans, then POST to /v1/customers/{customer_id}/archive

this operation is irreversible through standard API endpoints, so billing and usage reconciliation must be completed beforehand.

Webhooks are available for event-driven triggers including invoice.finalized, customer.plan.added, and alert.triggered.

Provision a new billing customer and attach a plan

1. POST /v1/customers with name and ingest_aliases to create the customer record.
2. Note the returned customer id.
3. POST /v1/customers/{customer_id}/setBillingConfig to link a Stripe or other billing provider customer ID.
4. POST /v1/customers/{customer_id}/plans/add with the target plan_id and a future starting_on date.

Watch out for: ingest_aliases must match the customer_id or alias used in usage event ingestion; mismatch causes events to be dropped or misattributed.

Retrieve and paginate all customers

1. GET /v1/customers?limit=100 to fetch the first page.
2. Check response for next_page cursor token.
3. If next_page is present, GET /v1/customers?next_page= for subsequent pages.
4. Repeat until next_page is absent in the response.

Watch out for: Cursor tokens are opaque and time-sensitive; do not cache or reuse tokens across sessions.

Archive a churned customer

1. Confirm the customer has no active plans via GET /v1/customers/{customer_id}/plans.
2. POST /v1/customers/{customer_id}/archive to deactivate the customer.
3. Verify the customer no longer appears in active customer list responses.

Watch out for: Archiving is irreversible via the API; ensure all billing and usage data has been reconciled before archiving.

The most consequential API gotcha is the semantic mismatch: Metronome customers are billing entities, not human users, which means this API cannot substitute for an identity provider or feed a human identity graph without a separate mapping layer. Rate limits are not publicly documented; production integrations must implement exponential backoff defensively.

Metronome uses POST rather than PATCH for some update operations - verify the current API reference before assuming standard REST semantics. No SCIM support exists, so customer lifecycle cannot be delegated to an IdP; all provisioning and archiving must flow through the REST API or dashboard explicitly.