Skip to content
Metronome Docs
  • Auto
  • Light
  • Dark
Talk to an expert

Customers

API Reference
V1

Customers

Customers

Archive a customer
post/v1/customers/archive
Create a customer
post/v1/customers
List customers
get/v1/customers
Get billable metrics for a customer
get/v1/customers/{customer_id}/billable-metrics
Get customer costs
get/v1/customers/{customer_id}/costs
Preview events
post/v1/customers/{customer_id}/previewEvents
Get a customer
get/v1/customers/{customer_id}
Create or update customer ingest aliases
post/v1/customers/{customer_id}/setIngestAliases
Update a customer name
post/v1/customers/{customer_id}/setName
Update a customer configuration
post/v1/customers/{customer_id}/updateConfig
Customer
Customerobject
ShowShow
idstring

the Metronome ID of the customer

formatuuid
external_idstring

(deprecated, use ingest_aliases instead) the first ID (Metronome or ingest alias) that can be used in usage events

ingest_aliasesarray of string

aliases for this customer that can be used instead of the Metronome customer ID in usage events

namestring
custom_fieldsmap
optional
Customer Detail
CustomerDetailobject
ShowShow
idstring

the Metronome ID of the customer

formatuuid
created_atstring

RFC 3339 timestamp indicating when the customer was created.

formatdate-time
custom_fieldsmap
customer_configobject
Hide ParametersShow Parameters
salesforce_account_idstring

The Salesforce account ID for the customer

external_idstring

(deprecated, use ingest_aliases instead) the first ID (Metronome or ingest alias) that can be used in usage events

ingest_aliasesarray of string

aliases for this customer that can be used instead of the Metronome customer ID in usage events

namestring
archived_atstring
optional

RFC 3339 timestamp indicating when the customer was archived. Null if the customer is active.

formatdate-time
current_billable_statusobject
optional

This field's availability is dependent on your client's configuration.

Hide ParametersShow Parameters
valueenum
"billable" OR "unbillable"
Hide ParametersShow Parameters
"billable"
"unbillable"
effective_atstring
optional
formatdate-time

CustomersAlerts

List customer alerts
post/v1/customer-alerts/list
Reset an alert for a customer
post/v1/customer-alerts/reset
Get an alert
post/v1/customer-alerts/get
Customer Alert
CustomerAlertobject
ShowShow
alertobject
Hide ParametersShow Parameters
idstring

the Metronome ID of the alert

namestring

Name of the alert

statusenum
"enabled" OR "archived" OR "disabled"

Status of the alert

Hide ParametersShow Parameters
"enabled"
"archived"
"disabled"
thresholdnumber

Threshold value of the alert policy

typeenum
"low_credit_balance_reached" OR "spend_threshold_reached" OR "monthly_invoice_total_spend_threshold_reached" OR 11 more

Type of the alert

Hide ParametersShow Parameters
"low_credit_balance_reached"
"spend_threshold_reached"
"monthly_invoice_total_spend_threshold_reached"
"low_remaining_days_in_plan_reached"
"low_remaining_credit_percentage_reached"
"usage_threshold_reached"
"low_remaining_days_for_commit_segment_reached"
"low_remaining_commit_balance_reached"
"low_remaining_commit_percentage_reached"
"low_remaining_days_for_contract_credit_segment_reached"
"low_remaining_contract_credit_balance_reached"
"low_remaining_contract_credit_percentage_reached"
"low_remaining_contract_credit_and_commit_balance_reached"
"invoice_total_reached"
updated_atstring

Timestamp for when the alert was last updated

formatdate-time
credit_grant_type_filtersarray of string
optional

An array of strings, representing a way to filter the credit grant this alert applies to, by looking at the credit_grant_type field on the credit grant. This field is only defined for CreditPercentage and CreditBalance alerts

credit_typeidstringnamestringCreditTypeData
optional
custom_field_filtersarray of object
optional

A list of custom field filters for alert types that support advanced filtering

Hide ParametersShow Parameters
entityenum
"Contract" OR "Commit" OR "ContractCredit"
Hide ParametersShow Parameters
"Contract"
"Commit"
"ContractCredit"
keystring
valuestring
group_key_filterobject
optional

Scopes alert evaluation to a specific presentation group key on individual line items. Only present for spend alerts.

Hide ParametersShow Parameters
keystring
valuestring
group_valuesarray of object
optional

Only present for spend_threshold_reached alerts. Scope alert to a specific group key on individual line items.

Hide ParametersShow Parameters
keystring
valuestring
invoice_types_filterarray of string
optional

Only supported for invoice_total_reached alerts. A list of invoice types to evaluate.

uniqueness_keystring
optional

Prevents the creation of duplicates. If a request to create a record is made with a previously used uniqueness key, a new record will not be created and the request will fail with a 409 error.

minLength1
maxLength128
customer_statusenum
"ok" OR "in_alarm" OR "evaluating"

The status of the customer alert. If the alert is archived, null will be returned.

Hide ParametersShow Parameters
"ok"
"in_alarm"
"evaluating"
triggered_bystring
optional

If present, indicates the reason the alert was triggered.

CustomersBilling Config

Set a customer billing configuration
post/v1/customers/{customer_id}/billing-config/{billing_provider_type}
Delete a customer billing configuration
delete/v1/customers/{customer_id}/billing-config/{billing_provider_type}
Get a customer billing configuration
get/v1/customers/{customer_id}/billing-config/{billing_provider_type}

CustomersCommits

Create a commit
post/v1/contracts/customerCommits/create
List commits
post/v1/contracts/customerCommits/list
Update the commit end date
post/v1/contracts/customerCommits/updateEndDate

CustomersCredits

Create a credit
post/v1/contracts/customerCredits/create
List credits
post/v1/contracts/customerCredits/list
Update the credit end date
post/v1/contracts/customerCredits/updateEndDate

CustomersInvoices

Add a one time charge
post/v1/customers/{customer_id}/addCharge
List invoices
get/v1/customers/{customer_id}/invoices
List invoice breakdowns
get/v1/customers/{customer_id}/invoices/breakdowns
Get an invoice
get/v1/customers/{customer_id}/invoices/{invoice_id}
Invoice
Invoiceobject
ShowShow
idstring
formatuuid
credit_typeidstringnamestringCreditTypeData
customer_idstring
formatuuid
line_itemsarray of object
Hide ParametersShow Parameters
credit_typeidstringnamestringCreditTypeData
namestring
totalnumber
applied_commit_or_creditobject
optional

Details about the credit or commit that was applied to this line item. Only present on line items with product of USAGE, SUBSCRIPTION or COMPOSITE types.

Hide ParametersShow Parameters
idstring
formatuuid
typeenum
"PREPAID" OR "POSTPAID" OR "CREDIT"
Hide ParametersShow Parameters
"PREPAID"
"POSTPAID"
"CREDIT"
commit_custom_fieldsmap
optional
commit_idstring
optional

For line items with product of USAGE, SUBSCRIPTION, or COMPOSITE types, the ID of the credit or commit that was applied to this line item. For line items with product type of FIXED, the ID of the prepaid or postpaid commit that is being paid for.

formatuuid
commit_netsuite_item_idstring
optional
commit_netsuite_sales_order_idstring
optional
commit_segment_idstring
optional
formatuuid
commit_typestring
optional

PrepaidCommit (for commit types PREPAID and CREDIT) or PostpaidCommit (for commit type POSTPAID).

custom_fieldsmap
optional
discount_custom_fieldsmap
optional
discount_idstring
optional

ID of the discount applied to this line item.

formatuuid
ending_beforestring
optional

The line item's end date (exclusive).

formatdate-time
group_keystring
optional
group_valuestring
optional
is_proratedboolean
optional

Indicates whether the line item is prorated for SUBSCRIPTION type product.

list_pricerate_typeenumcredit_typeCreditTypeDatacustom_ratemapis_proratedbooleanpricenumberpricing_group_valuesmapquantitynumbertiersarray of Tieruse_list_pricesbooleanRate
optional

Only present for contract invoices and when the include_list_prices query parameter is set to true. This will include the list rate for the charge if applicable. Only present for usage and subscription line items.

metadatastring
optional
netsuite_invoice_billing_endstring
optional

The end date for the billing period on the invoice.

formatdate-time
netsuite_invoice_billing_startstring
optional

The start date for the billing period on the invoice.

formatdate-time
netsuite_item_idstring
optional
postpaid_commitobject
optional

Only present for line items paying for a postpaid commit true-up.

Hide ParametersShow Parameters
idstring
formatuuid
presentation_group_valuesmap
optional

Includes the presentation group values associated with this line item if presentation group keys are used.

pricing_group_valuesmap
optional

Includes the pricing group values associated with this line item if dimensional pricing is used.

product_custom_fieldsmap
optional
product_idstring
optional

ID of the product associated with the line item.

formatuuid
product_tagsarray of string
optional

The current product tags associated with the line item's product_id.

product_typestring
optional

The type of the line item's product. Possible values are FixedProductListItem (for FIXED type products), UsageProductListItem (for USAGE type products), SubscriptionProductListItem (for SUBSCRIPTION type products) or CompositeProductListItem (for COMPOSITE type products). For scheduled charges, commit and credit payments, the value is FixedProductListItem.

professional_service_custom_fieldsmap
optional
professional_service_idstring
optional
formatuuid
quantitynumber
optional

The quantity associated with the line item.

reseller_typeenum
optional
"AWS" OR "AWS_PRO_SERVICE" OR "GCP" OR "GCP_PRO_SERVICE"
Hide ParametersShow Parameters
"AWS"
"AWS_PRO_SERVICE"
"GCP"
"GCP_PRO_SERVICE"
scheduled_charge_custom_fieldsmap
optional
scheduled_charge_idstring
optional

ID of scheduled charge.

formatuuid
starting_atstring
optional

The line item's start date (inclusive).

formatdate-time
sub_line_itemsarray of object
optional
Hide ParametersShow Parameters
custom_fieldsmap
namestring
quantitynumber
subtotalnumber
charge_idstring
optional
formatuuid
credit_grant_idstring
optional
formatuuid
end_datestring
optional

The end date for the charge (for seats charges only).

formatdate-time
pricenumber
optional

the unit price for this charge, present only if the charge is not tiered and the quantity is nonzero

start_datestring
optional

The start date for the charge (for seats charges only).

formatdate-time
tier_periodobject
optional

when the current tier started and ends (for tiered charges only)

Hide ParametersShow Parameters
starting_atstring
formatdate-time
ending_beforestring
optional
formatdate-time
tiersarray of object
optional
Hide ParametersShow Parameters
pricenumber
quantitynumber
starting_atnumber

at what metric amount this tier begins

subtotalnumber
subscription_custom_fieldsmap
optional
tierobject
optional

Populated if the line item has a tiered price.

Hide ParametersShow Parameters
levelnumber
starting_atstring
sizestring
optional
unit_pricenumber
optional

The unit price associated with the line item.

statusstring
totalnumber
typestring
amendment_idstring
optional
formatuuid
billable_statusenum
optional
"billable" OR "unbillable"

This field's availability is dependent on your client's configuration.

Hide ParametersShow Parameters
"billable"
"unbillable"
contract_custom_fieldsmap
optional
contract_idstring
optional
formatuuid
correction_recordobject
optional
Hide ParametersShow Parameters
corrected_invoice_idstring
formatuuid
memostring
reasonstring
corrected_external_invoiceobject
optional
Hide ParametersShow Parameters
billing_provider_typeenum
"aws_marketplace" OR "stripe" OR "netsuite" OR 5 more
Hide ParametersShow Parameters
"aws_marketplace"
"stripe"
"netsuite"
"custom"
"azure_marketplace"
"quickbooks_online"
"workday"
"gcp_marketplace"
external_statusenum
optional
"DRAFT" OR "FINALIZED" OR "PAID" OR 8 more
Hide ParametersShow Parameters
"DRAFT"
"FINALIZED"
"PAID"
"UNCOLLECTIBLE"
"VOID"
"DELETED"
"PAYMENT_FAILED"
"INVALID_REQUEST_ERROR"
"SKIPPED"
"SENT"
"QUEUED"
invoice_idstring
optional
issued_at_timestampstring
optional
formatdate-time
created_atstring
optional

When the invoice was created (UTC). This field is present for correction invoices only.

formatdate-time
custom_fieldsmap
optional
customer_custom_fieldsmap
optional
end_timestampstring
optional

End of the usage period this invoice covers (UTC)

formatdate-time
external_invoiceobject
optional
Hide ParametersShow Parameters
billing_provider_typeenum
"aws_marketplace" OR "stripe" OR "netsuite" OR 5 more
Hide ParametersShow Parameters
"aws_marketplace"
"stripe"
"netsuite"
"custom"
"azure_marketplace"
"quickbooks_online"
"workday"
"gcp_marketplace"
external_statusenum
optional
"DRAFT" OR "FINALIZED" OR "PAID" OR 8 more
Hide ParametersShow Parameters
"DRAFT"
"FINALIZED"
"PAID"
"UNCOLLECTIBLE"
"VOID"
"DELETED"
"PAYMENT_FAILED"
"INVALID_REQUEST_ERROR"
"SKIPPED"
"SENT"
"QUEUED"
invoice_idstring
optional
issued_at_timestampstring
optional
formatdate-time
invoice_adjustmentsarray of object
optional
Hide ParametersShow Parameters
credit_typeidstringnamestringCreditTypeData
namestring
totalnumber
credit_grant_custom_fieldsmap
optional
credit_grant_idstring
optional
issued_atstring
optional

When the invoice was issued (UTC)

formatdate-time
net_payment_terms_daysnumber
optional
netsuite_sales_order_idstring
optional

This field's availability is dependent on your client's configuration.

plan_custom_fieldsmap
optional
plan_idstring
optional
formatuuid
plan_namestring
optional
reseller_royaltyobject
optional

Only present for contract invoices with reseller royalties.

Hide ParametersShow Parameters
fractionstring
netsuite_reseller_idstring
reseller_typeenum
"AWS" OR "AWS_PRO_SERVICE" OR "GCP" OR "GCP_PRO_SERVICE"
Hide ParametersShow Parameters
"AWS"
"AWS_PRO_SERVICE"
"GCP"
"GCP_PRO_SERVICE"
aws_optionsobject
optional
Hide ParametersShow Parameters
aws_account_numberstring
optional
aws_offer_idstring
optional
aws_payer_reference_idstring
optional
gcp_optionsobject
optional
Hide ParametersShow Parameters
gcp_account_idstring
optional
gcp_offer_idstring
optional
salesforce_opportunity_idstring
optional

This field's availability is dependent on your client's configuration.

start_timestampstring
optional

Beginning of the usage period this invoice covers (UTC)

formatdate-time
subtotalnumber
optional

CustomersNamed Schedules

Get a customer's named schedule
post/v1/customers/getNamedSchedule
Update a customer's named schedule
post/v1/customers/updateNamedSchedule

CustomersPlans

Add a plan to a customer
post/v1/customers/{customer_id}/plans/add
End a customer plan
post/v1/customers/{customer_id}/plans/{customer_plan_id}/end
List customer plans
get/v1/customers/{customer_id}/plans
Get the plan adjustments for a customer
get/v1/customers/{customer_id}/plans/{customer_plan_id}/priceAdjustments