[Customers](https://docs.metronome.com/provisioning/create-customers/) in Metronome represent your users for all billing and reporting. Use these endpoints to create, retrieve, update, and archive customers and their billing configuration.
openapi: 3.0.1
info:
title: Metronome Alerts Customers API
version: 1.0.0
description: '[Alerts](https://docs.metronome.com/connecting-metronome/alerts/) monitor customer spending, balances, and other billing factors. Use these endpoints to create, retrieve, and archive customer alerts. To view sample alert payloads by alert type, navigate [here.](https://docs.metronome.com/manage-product-access/create-manage-alerts/#webhook-notifications)'
servers:
- url: https://api.metronome.com
description: Production server
security:
- bearerAuth: []
tags:
- name: Customers
description: '[Customers](https://docs.metronome.com/provisioning/create-customers/) in Metronome represent your users for all billing and reporting. Use these endpoints to create, retrieve, update, and archive customers and their billing configuration.'
paths:
/v1/customers/setBillableStatus:
post:
x-mint:
groups:
- client_id:5b9e3072-415b-4842-94f0-0b6700c8b6be
- client_id:179e395f-5349-4fe2-bf12-64ab4e5bc560
- client_id:f157d376-0781-4ef3-9db9-775a9052148e
- client_id:7dd2f652-7629-4925-9069-77f5c5d3db37
- client_id:c0ce3dc0-6d3e-4f6b-aadf-dfb90f2bf9f5
- client_id:cf874b25-ca3b-460b-b6fe-5f33b3c2ea33
description: Set a customer's billable status. This endpoint's availability is dependent on your client's configuration. Metronome 1.0 plan invoices are not supported.
operationId: setCustomerBillableStatus-v1
summary: Set customer billable status
tags:
- Customers
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SetCustomerBillableStatusPayload'
example:
customer_id: 04ca7e72-4229-4a6e-ab11-9f7376fccbcb
billable_status: billable
effective_at: '2021-01-01T00:00:00Z'
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
required:
- data
properties:
data:
type: object
required:
- id
- current_billable_status
properties:
id:
type: string
format: uuid
current_billable_status:
$ref: '#/components/schemas/BillableStatus'
example:
data:
id: 8deed800-1b7a-495d-a207-6c52bac54dc9
current_billable_status: billable
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
$ref: '#/components/responses/NotFound'
/v1/customers/archive:
post:
description: "Use this endpoint to archive a customer while preserving auditability. Archiving a customer will automatically archive all contracts as of the current date and void all corresponding invoices. Use this endpoint if a customer is onboarded by mistake.\n\n### Usage guidelines:\n- Once a customer is archived, it cannot be unarchived.\n- Archived customers can still be viewed through the API or the UI for audit purposes. \n- Ingest aliases remain idempotent for archived customers. In order to reuse an ingest alias, first remove the ingest alias from the customer prior to archiving.\n- Any notifications associated with the customer will no longer be triggered.\n"
operationId: archiveCustomer-v1
summary: Archive a customer
tags:
- Customers
requestBody:
description: The ID of the customer to archive
content:
application/json:
schema:
$ref: '#/components/schemas/Id'
example:
id: 8deed800-1b7a-495d-a207-6c52bac54dc9
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
required:
- data
properties:
data:
$ref: '#/components/schemas/Id'
example:
data:
id: 8deed800-1b7a-495d-a207-6c52bac54dc9
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
$ref: '#/components/responses/NotFound'
/v1/customers/{customer_id}:
get:
description: 'Get detailed information for a specific customer by their Metronome ID. Returns customer profile data including name, creation date, ingest aliases, configuration settings, and custom fields. Use this endpoint to fetch complete customer details for billing operations or account management.
Note: If searching for a customer billing configuration, use the `/getCustomerBillingConfigurations` endpoint.
'
operationId: getCustomer-v1
summary: Get a customer
parameters:
- $ref: '#/components/parameters/CustomerId'
tags:
- Customers
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
required:
- data
properties:
data:
$ref: '#/components/schemas/CustomerDetail'
example:
data:
id: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc
created_at: '2024-01-01T00:00:00.000Z'
updated_at: '2024-01-01T00:00:00.000Z'
external_id: team@example.com
ingest_aliases:
- team@example.com
name: Example, Inc.
customer_config:
salesforce_account_id: 0015500001WO1ZiABL
custom_fields:
x_account_id: KyVnHhSBWl7eY2bl
/v1/customers:
get:
description: 'Gets a paginated list of all customers in your Metronome account. Use this endpoint to browse your customer base, implement customer search functionality, or sync customer data with external systems. Returns customer details including IDs, names, and configuration settings. Supports filtering and pagination parameters for efficient data retrieval.
'
operationId: listCustomers-v1
summary: List customers
parameters:
- $ref: '#/components/parameters/PageLimit'
- $ref: '#/components/parameters/NextPage'
- in: query
name: ingest_alias
description: Filter the customer list by ingest_alias
required: false
schema:
type: string
- in: query
name: customer_ids
description: Filter the customer list by customer_id. Up to 100 ids can be provided.
required: false
schema:
type: array
items:
type: string
- in: query
name: only_archived
description: Filter the customer list to only return archived customers. By default, only active customers are returned.
required: false
schema:
type: boolean
- in: query
name: salesforce_account_ids
description: Filter the customer list by salesforce_account_id. Up to 100 ids can be provided.
required: false
schema:
type: array
maxItems: 100
items:
type: string
tags:
- Customers
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
required:
- data
- next_page
properties:
data:
type: array
items:
$ref: '#/components/schemas/CustomerDetail'
next_page:
type: string
nullable: true
example:
data:
- id: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc
external_id: team@example.com
created_at: '2024-01-01T00:00:00.000Z'
updated_at: '2024-01-01T00:00:00.000Z'
ingest_aliases:
- team@example.com
name: Example, Inc.
customer_config:
salesforce_account_id: 0015500001WO1ZiABL
custom_fields:
x_account_id: KyVnHhSBWl7eY2bl
next_page: null
post:
description: "Create a new customer in Metronome and optionally the billing configuration (recommended) which dictates where invoices for the customer will be sent or where payment will be collected. \n\n### Use this endpoint to:\nExecute your customer provisioning workflows for either PLG motions, where customers originate in your platform, or SLG motions, where customers originate in your sales system.\n\n### Key response fields: \nThis end-point returns the `customer_id` created by the request. This id can be used to fetch relevant billing configurations and create contracts.\n\n### Example workflow:\n- Generally, Metronome recommends first creating the customer in the downstream payment / ERP system when payment method is collected and then creating the customer in Metronome using the response (i.e. `customer_id`) from the downstream system. If you do not create a billing configuration on customer creation, you can add it later. \n- Once a customer is created, you can then create a contract for the customer. In the contract creation process, you will need to add the customer billing configuration to the contract to ensure Metronome invoices the customer correctly. This is because a customer can have multiple configurations.\n- As part of the customer creation process, set the ingest alias for the customer which will ensure usage is accurately mapped to the customer. Ingest aliases can be added or changed after the creation process as well.\n\n### Usage guidelines:\nFor details on different billing configurations for different systems, review the `/setCustomerBillingConfiguration` end-point.\n"
operationId: createCustomer-v1
summary: Create a customer
tags:
- Customers
requestBody:
description: The customer to create
content:
application/json:
schema:
$ref: '#/components/schemas/LegacyCreateCustomerPayload'
example:
ingest_aliases:
- team@example.com
name: Example, Inc.
customer_billing_provider_configurations:
- billing_provider: stripe
delivery_method: direct_to_billing_provider
configuration:
stripe_customer_id: cus_123
stripe_collection_method: charge_automatically
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
required:
- data
properties:
data:
$ref: '#/components/schemas/Customer'
example:
data:
id: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc
external_id: team@example.com
ingest_aliases:
- team@example.com
name: Aperture, Inc.
'409':
description: A customer with this ID already exists
content:
application/json:
schema:
type: object
properties:
message:
type: string
/v1/customers/{customer_id}/setIngestAliases:
post:
description: "Sets the ingest aliases for a customer. Use this endpoint to associate a Metronome customer with an internal ID for easier tracking between systems. Ingest aliases can be used in the `customer_id` field when sending usage events to Metronome. \n\n### Usage guidelines:\n- This call is idempotent and fully replaces the set of ingest aliases for the given customer.\n- Switching an ingest alias from one customer to another will associate all corresponding usage to the new customer.\n- Use multiple ingest aliases to model child organizations within a single Metronome customer.\n"
operationId: setIngestAliases-v1
summary: Create or update customer ingest aliases
parameters:
- $ref: '#/components/parameters/CustomerId'
tags:
- Customers
requestBody:
description: The aliases to add
content:
application/json:
schema:
$ref: '#/components/schemas/SetIngestAliasesPayload'
example:
ingest_aliases:
- team@example.com
responses:
'200':
description: Success
/v1/customers/{customer_id}/setName:
post:
description: 'Updates the display name for a customer record. Use this to correct customer names, update business names after rebranding, or maintain accurate customer information for invoicing and reporting. Returns the updated customer object with the new name applied immediately across all billing documents and interfaces.
'
operationId: setCustomerName-v1
summary: Update a customer name
parameters:
- $ref: '#/components/parameters/CustomerId'
tags:
- Customers
requestBody:
description: The customer name
content:
application/json:
schema:
$ref: '#/components/schemas/SetCustomerNamePayload'
example:
name: Example, Inc.
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
required:
- data
properties:
data:
$ref: '#/components/schemas/Customer'
example:
data:
id: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc
external_id: team@example.com
ingest_aliases:
- team@example.com
name: Example, Inc.
/v1/customers/{customer_id}/updateConfig:
post:
description: 'Update configuration settings for a specific customer, such as external system integrations (e.g., Salesforce account ID) and other customer-specific billing parameters. Use this endpoint to modify customer configurations without affecting core customer data like name or ingest aliases.
'
operationId: updateCustomerConfig-v1
summary: Update a customer configuration
parameters:
- $ref: '#/components/parameters/CustomerId'
tags:
- Customers
requestBody:
description: The configuration for a specific customer
content:
application/json:
schema:
$ref: '#/components/schemas/CustomerConfigPayload'
example:
salesforce_account_id: 0015500001WO1ZiABL
responses:
'200':
description: Success
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
$ref: '#/components/responses/NotFound'
/v1/getCustomerBillingProviderConfigurations:
post:
description: 'Returns all billing configurations previously set for the customer. Use during the contract provisioning process to fetch the `billing_provider_configuration_id` needed to set the contract billing configuration.
'
operationId: getCustomerBillingProviderConfigurations-v1
summary: Fetch billing provider configurations for a customer
tags:
- Customers
requestBody:
description: The customer id for which to fetch billing provider configurations
content:
application/json:
schema:
type: object
required:
- customer_id
properties:
customer_id:
type: string
format: uuid
include_archived:
type: boolean
example:
customer_id: 6a37bb88-8538-48c5-b37b-a41c836328bd
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
required:
- data
properties:
data:
type: array
items:
$ref: '#/components/schemas/CustomerBillingProviderConfiguration'
example:
data:
- id: e045c62b-65e7-4e84-a924-3f06f8b621d0
billing_provider: stripe
customer_id: 6a37bb88-8538-48c5-b37b-a41c836328bd
configuration:
stripe_customer_id: cus_SB7Rq5UAkSmrR3
stripe_collection_method: charge_automatically
delivery_method: direct_to_billing_provider
delivery_method_configuration:
stripe_account_id: acct_1P6FywIkTQSg6Mm3
leave_invoices_in_draft: false
skip_zero_dollar_invoices: false
export_invoice_sub_line_items: false
include_zero_quantity_sub_line_items: true
stripe_invoice_quantity_always_string: false
set_effective_at_date_to_inclusive_period_end: false
archived_at: null
delivery_method_id: 4422e46f-b374-4159-97e3-300208cdb2e2
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/v1/getCustomerRevenueSystemConfigurations:
post:
x-mint:
groups:
- ff:revenue-rec-configurations-enabled
description: 'Returns all revenue system configurations previously set for the customer.
'
operationId: getCustomerRevenueSystemConfigurations-v1
summary: Fetch revenue system configurations for a customer
tags:
- Customers
requestBody:
description: The customer id for which to fetch revenue system configurations
content:
application/json:
schema:
type: object
required:
- customer_id
properties:
customer_id:
type: string
format: uuid
provider:
$ref: '#/components/schemas/RevenueSystemProviderType'
description: Filter configurations by revenue system provider
include_archived:
type: boolean
description: Whether to include archived configurations
example:
customer_id: 6a37bb88-8538-48c5-b37b-a41c836328bd
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
required:
- data
properties:
data:
type: array
items:
$ref: '#/components/schemas/CustomerRevenueSystemConfiguration'
example:
data:
- id: e045c62b-65e7-4e84-a924-3f06f8b621d0
provider: netsuite
customer_id: 6a37bb88-8538-48c5-b37b-a41c836328bd
configuration:
netsuite_customer_id: '12345'
delivery_method_id: 4422e46f-b374-4159-97e3-300208cdb2e2
delivery_method: direct_to_billing_provider
delivery_method_configuration:
netsuite_account_id: acct_123
archived_at: null
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/v1/setCustomerBillingProviderConfigurations:
post:
description: "Create a billing configuration for a customer. Once created, these configurations are available to associate to a contract and dictates which downstream system to collect payment in or send the invoice to. You can create multiple configurations per customer. The configuration formats are distinct for each downstream provider.\n\n### Use this endpoint to:\n- Add the initial configuration to an existing customer. Once created, the billing configuration can then be associated to the customer's contract.\n- Add a new configuration to an existing customer. This might be used as part of an upgrade or downgrade workflow where the customer was previously billed through system A (e.g. Stripe) but will now be billed through system B (e.g. AWS). Once created, the new configuration can then be associated to the customer's contract.\n- Multiple configurations can be added per destination. For example, you can create two Stripe billing configurations for a Metronome customer that each have a distinct `collection_method`.\n\n### Delivery method options:\n- `direct_to_billing_provider`: Use when Metronome should send invoices directly to the billing provider's API (e.g., Stripe, NetSuite). This is the most common method for automated billing workflows.\n- `tackle`: Use specifically for AWS Marketplace transactions that require Tackle's co-selling platform for partner attribution and commission tracking.\n- `aws_sqs`: Use when you want invoice data delivered to an AWS SQS queue for custom processing before sending to your billing system.\n- `aws_sns`: Use when you want invoice notifications published to an AWS SNS topic for event-driven billing workflows.\n\n### Key response fields: \nThe id for the customer billing configuration. This id can be used to associate the billing configuration to a contract.\n\n### Usage guidelines:\nMust use the `delivery_method_id` if you have multiple Stripe accounts connected to Metronome.\n"
operationId: setCustomerBillingProviderConfigurations-v1
summary: Set billing provider configurations for a customer
tags:
- Customers
requestBody:
description: The details of the billing provider configurations to insert
content:
application/json:
schema:
type: object
required:
- data
properties:
data:
type: array
items:
$ref: '#/components/schemas/CustomerBillingProviderConfigurationInput'
example:
data:
- customer_id: 4db51251-61de-4bfe-b9ce-495e244f3491
billing_provider: stripe
configuration:
stripe_customer_id: cus_1234
stripe_collection_method: charge_automatically
leave_stripe_invoices_in_draft: true
delivery_method: direct_to_billing_provider
- customer_id: 4db51251-61de-4bfe-b9ce-495e244f3491
billing_provider: aws_marketplace
configuration:
aws_customer_id: ABC123ABC12
aws_product_code: my_product
aws_region: us-west-1
delivery_method: direct_to_billing_provider
- customer_id: 4db51251-61de-4bfe-b9ce-495e244f3491
billing_provider: azure_marketplace
configuration:
azure_subscription_id: my_subscription
delivery_method_id: 5b9e3072-415b-4842-94f0-0b6700c8b6be
- customer_id: 4db51251-61de-4bfe-b9ce-495e244f3491
billing_provider: aws_marketplace
configuration:
aws_customer_id: ABC123ABC12
aws_product_code: my_product
aws_region: us-west-1
aws_is_subscription_product: true
delivery_method: direct_to_billing_provider
- customer_id: 4db51251-61de-4bfe-b9ce-495e244f3491
billing_provider: gcp_marketplace
configuration:
gcp_entitlement_id: my_entitlement
gcp_service_name: my.service.endpoint.goog
delivery_method: direct_to_billing_provider
- customer_id: 4db51251-61de-4bfe-b9ce-495e244f3491
billing_provider: netsuite
configuration:
netsuite_customer_id: '12345'
delivery_method: direct_to_billing_provider
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
required:
- data
properties:
data:
type: array
items:
$ref: '#/components/schemas/CustomerBillingProviderConfigurationOutput'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/v1/archiveCustomerBillingProviderConfigurations:
post:
description: "Deprecate an existing billing configuration for a customer to handle churn or billing and collection preference changes. Archiving a billing configuration takes effect immediately. If there are active contracts using the configuration, Metronome will archive the configuration on the contract and immediately stop metering to downstream systems.\n\n### Use this endpoint to:\n- Remove billing provider customer data and configurations when no longer needed\n- Clean up test or deprecated billing provider configurations\n- Free up uniqueness keys for reuse with new billing provider configurations\n- Disable threshold recharge configurations associated with archived billing providers\n\n### Key response fields:\nA successful response returns:\n- `success`: Boolean indicating the operation completed successfully\n- `error`: Null on success, error message on failure\n\n### Usage guidelines:\n- Archiving a contract configuration during a grace period will result in the invoice not being sent to the customer\n- Automatically disables both spend-based and credit-based threshold recharge configurations for contracts using the archived billing provider \n- You can archive multiple configurations for a single customer in a single request, but any validation failures for an individual configuration will prevent the entire operation from succeeding\n"
operationId: archiveCustomerBillingProviderConfigurations-v1
summary: Archive billing provider configurations for a customer
tags:
- Customers
requestBody:
description: The ids of the billing provider configurations to archive
content:
application/json:
schema:
$ref: '#/components/schemas/CustomerBillingProviderArchivePayload'
example:
customer_billing_provider_configuration_ids:
- 4db51251-61de-4bfe-b9ce-495e244f3491
- 4db51251-61de-4bfe-b9ce-495e244f3491
customer_id: 20a060d1-aa80-41d4-8bb2-4f3091b93903
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
required:
- data
properties:
data:
$ref: '#/components/schemas/CustomerBillingProviderArchivePayload'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/v1/setCustomerRevenueSystemConfigurations:
post:
x-mint:
groups:
- ff:revenue-rec-configurations-enabled
description: "Create a revenue system configuration for a customer. Once created, these configurations are available to associate to a contract and dictates which downstream system to use for revenue workflows. The configuration formats are distinct for each downstream provider.\n\n### Use this endpoint to:\n- Add the initial configuration to an existing customer. Once created, the revenue system configuration can then be associated to the customer's contract.\n- Add a new configuration to an existing customer.\n\n### Key response fields: \nReturns the inserted configuration objects, including the id of the revenue system configuration(s). These ids can be used to associate a revenue system to a contract.\n"
operationId: setCustomerRevenueSystemConfigurations-v1
summary: Set revenue system configurations for a customer
tags:
- Customers
requestBody:
description: The details of the revenue system configurations to insert
content:
application/json:
schema:
type: object
required:
- data
properties:
data:
type: array
items:
$ref: '#/components/schemas/CustomerRevenueSystemConfigurationInput'
example:
data:
- customer_id: 4db51251-61de-4bfe-b9ce-495e244f3491
provider: netsuite
configuration:
netsuite_customer_id: 12345
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
required:
- data
properties:
data:
type: array
items:
$ref: '#/components/schemas/CustomerRevenueSystemConfiguration'
example:
data:
- id: e045c62b-65e7-4e84-a924-3f06f8b621d0
customer_id: 6a37bb88-8538-48c5-b37b-a41c836328bd
delivery_method_id: ebacc0cc-56ac-4cfa-971b-4fc3f58ee960
provider: netsuite
configuration:
netsuite_customer_id: '12345'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/v1/archiveCustomerRevenueSystemConfigurations:
post:
x-mint:
groups:
- ff:revenue-rec-configurations-enabled
description: 'Archive existing revenue system configurations for a customer. Archiving a revenue system configuration takes effect immediately.
### Use this endpoint to:
- Remove revenue system configurations when no longer needed
- Clean up test or deprecated revenue system configurations
### Key response fields:
A successful response returns:
- `customer_id`: The customer ID the configurations belong to
- `customer_revenue_system_configuration_ids`: The archived configuration IDs
'
operationId: archiveCustomerRevenueSystemConfigurations-v1
summary: Archive revenue system configurations for a customer
tags:
- Customers
requestBody:
description: The ids of the revenue system configurations to archive
content:
application/json:
schema:
$ref: '#/components/schemas/CustomerRevenueS
# --- truncated at 32 KB (58 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/metronome/refs/heads/main/openapi/metronome-customers-api-openapi.yml