Customers

API Reference

V1

Customers

Customers

Archive a customer

v1.customers.archive(**kwargs) -> dataIDCustomerArchiveResponse

post/v1/customers/archive

Create a customer

v1.customers.create(**kwargs) -> dataCustomerCustomerCreateResponse

post/v1/customers

List customers

v1.customers.list(**kwargs) -> CursorPage<idStringcreated_atTimecustom_fieldshashcustomer_configobjectexternal_idStringingest_aliasesarraynameStringarchived_atTimecurrent_billable_statusobjectCustomerDetail>

get/v1/customers

Get billable metrics for a customer

v1.customers.list_billable_metrics(**kwargs) -> CursorPage<idStringnameStringaggregateStringaggregate_keysarrayaggregation_keyStringaggregation_typeunionarchived_atTimecustom_fieldshashevent_type_filterEventTypeFilterfilterhashgroup_byarraygroup_keysarrayproperty_filtersarraysqlStringCustomerListBillableMetricsResponse>

get/v1/customers/{customer_id}/billable-metrics

Get customer costs

v1.customers.list_costs(**kwargs) -> CursorPage<credit_typeshashend_timestampTimestart_timestampTimeCustomerListCostsResponse>

get/v1/customers/{customer_id}/costs

Preview events

v1.customers.preview_events(**kwargs) -> dataInvoiceCustomerPreviewEventsResponse

post/v1/customers/{customer_id}/previewEvents

Get a customer

v1.customers.retrieve(**kwargs) -> dataCustomerDetailCustomerRetrieveResponse

get/v1/customers/{customer_id}

Create or update customer ingest aliases

v1.customers.set_ingest_aliases(**kwargs) -> void

post/v1/customers/{customer_id}/setIngestAliases

Update a customer name

v1.customers.set_name(**kwargs) -> dataCustomerCustomerSetNameResponse

post/v1/customers/{customer_id}/setName

Update a customer configuration

v1.customers.update_config(**kwargs) -> void

post/v1/customers/{customer_id}/updateConfig

Customer

Customerclass

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

Array[String]

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

nameString

custom_fieldshash

optional

Hash[Symbol, String]

Customer Detail

CustomerDetailclass

ShowShow

idString

the Metronome ID of the customer

formatuuid

created_atTime

RFC 3339 timestamp indicating when the customer was created.

formatdate-time

custom_fieldshash

Hash[Symbol, String]

customer_configobject

{ salesforce_account_id}

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

Array[String]

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

nameString

archived_atTime

optional

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

formatdate-time

current_billable_statusobject

optional

{ value, effective_at}

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

Hide ParametersShow Parameters

valueunion

:billable | :unbillable

Hide ParametersShow Parameters

:billable

:unbillable

effective_atTime

optional

formatdate-time

CustomersAlerts

List customer alerts

v1.customers.alerts.list(**kwargs) -> dataarraynext_pageStringAlertListResponse

post/v1/customer-alerts/list

Reset an alert for a customer

v1.customers.alerts.reset(**kwargs) -> void

post/v1/customer-alerts/reset

Get an alert

v1.customers.alerts.retrieve(**kwargs) -> dataCustomerAlertAlertRetrieveResponse

post/v1/customer-alerts/get

Customer Alert

CustomerAlertclass

ShowShow

alertobject

{ id, name, status, 10 more}

Hide ParametersShow Parameters

idString

the Metronome ID of the alert

nameString

Name of the alert

statusunion

:enabled | :archived | :disabled

Status of the alert

Hide ParametersShow Parameters

:enabled

:archived

:disabled

thresholdFloat

Threshold value of the alert policy

typeunion

:low_credit_balance_reached | :spend_threshold_reached | :monthly_invoice_total_spend_threshold_reached | 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_atTime

Timestamp for when the alert was last updated

formatdate-time

credit_grant_type_filtersarray

optional

Array[String]

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

optional

Array[{ entity, key, value}]

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

Hide ParametersShow Parameters

entityunion

:Contract | :Commit | :ContractCredit

Hide ParametersShow Parameters

:Contract

:Commit

:ContractCredit

keyString

valueString

group_key_filterobject

optional

{ key, value}

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

optional

Array[{ key, value}]

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

optional

Array[String]

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_statusunion

:ok | :in_alarm | :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

v1.customers.billing_config.create(**kwargs) -> void

post/v1/customers/{customer_id}/billing-config/{billing_provider_type}

Delete a customer billing configuration

v1.customers.billing_config.delete(**kwargs) -> void

delete/v1/customers/{customer_id}/billing-config/{billing_provider_type}

Get a customer billing configuration

v1.customers.billing_config.retrieve(**kwargs) -> dataobjectBillingConfigRetrieveResponse

get/v1/customers/{customer_id}/billing-config/{billing_provider_type}

CustomersCommits

Create a commit

v1.customers.commits.create(**kwargs) -> dataIDCommitCreateResponse

post/v1/contracts/customerCommits/create

List commits

v1.customers.commits.list(**kwargs) -> dataarraynext_pageStringCommitListResponse

post/v1/contracts/customerCommits/list

Update the commit end date

v1.customers.commits.update_end_date(**kwargs) -> dataIDCommitUpdateEndDateResponse

post/v1/contracts/customerCommits/updateEndDate

CustomersCredits

Create a credit

v1.customers.credits.create(**kwargs) -> dataIDCreditCreateResponse

post/v1/contracts/customerCredits/create

List credits

v1.customers.credits.list(**kwargs) -> dataarraynext_pageStringCreditListResponse

post/v1/contracts/customerCredits/list

Update the credit end date

v1.customers.credits.update_end_date(**kwargs) -> dataIDCreditUpdateEndDateResponse

post/v1/contracts/customerCredits/updateEndDate

CustomersInvoices

Add a one time charge

v1.customers.invoices.add_charge(**kwargs) -> InvoiceAddChargeResponse

post/v1/customers/{customer_id}/addCharge

List invoices

v1.customers.invoices.list(**kwargs) -> CursorPage<idStringcredit_typeCreditTypeDatacustomer_idStringline_itemsarraystatusStringtotalFloattypeStringamendment_idStringbillable_statusunioncontract_custom_fieldshashcontract_idStringcorrection_recordobjectcreated_atTimecustom_fieldshashcustomer_custom_fieldshashend_timestampTimeexternal_invoiceobjectinvoice_adjustmentsarrayissued_atTimenet_payment_terms_daysFloatnetsuite_sales_order_idStringplan_custom_fieldshashplan_idStringplan_nameStringreseller_royaltyobjectsalesforce_opportunity_idStringstart_timestampTimesubtotalFloatInvoice>

get/v1/customers/{customer_id}/invoices

List invoice breakdowns

v1.customers.invoices.list_breakdowns(**kwargs) -> CursorPage<breakdown_end_timestampTimebreakdown_start_timestampTimeInvoiceListBreakdownsResponse>

get/v1/customers/{customer_id}/invoices/breakdowns

Get an invoice

v1.customers.invoices.retrieve(**kwargs) -> dataInvoiceInvoiceRetrieveResponse

get/v1/customers/{customer_id}/invoices/{invoice_id}

Invoice

Invoiceclass

ShowShow

idString

formatuuid

credit_typeidStringnameStringCreditTypeData

customer_idString

formatuuid

line_itemsarray

Array[{ credit_type, name, total, 37 more}]

Hide ParametersShow Parameters

credit_typeidStringnameStringCreditTypeData

nameString

totalFloat

applied_commit_or_creditobject

optional

{ id, type}

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

typeunion

:PREPAID | :POSTPAID | :CREDIT

Hide ParametersShow Parameters

:PREPAID

:POSTPAID

:CREDIT

commit_custom_fieldshash

optional

Hash[Symbol, String]

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_fieldshash

optional

Hash[Symbol, String]

discount_custom_fieldshash

optional

Hash[Symbol, String]

discount_idString

optional

ID of the discount applied to this line item.

formatuuid

ending_beforeTime

optional

The line item's end date (exclusive).

formatdate-time

group_keyString

optional

group_valueString

optional

is_proratedbool

optional

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

list_pricerate_typeunioncredit_typeCreditTypeDatacustom_ratehashis_proratedboolpriceFloatpricing_group_valueshashquantityFloattiersarrayuse_list_pricesboolRate

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_endTime

optional

The end date for the billing period on the invoice.

formatdate-time

netsuite_invoice_billing_startTime

optional

The start date for the billing period on the invoice.

formatdate-time

netsuite_item_idString

optional

postpaid_commitobject

optional

{ id}

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

Hide ParametersShow Parameters

idString

formatuuid

presentation_group_valueshash

optional

Hash[Symbol, String]

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

pricing_group_valueshash

optional

Hash[Symbol, String]

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

product_custom_fieldshash

optional

Hash[Symbol, String]

product_idString

optional

ID of the product associated with the line item.

formatuuid

product_tagsarray

optional

Array[String]

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_fieldshash

optional

Hash[Symbol, String]

professional_service_idString

optional

formatuuid

quantityFloat

optional

The quantity associated with the line item.

reseller_typeunion

optional

:AWS | :AWS_PRO_SERVICE | :GCP | :GCP_PRO_SERVICE

Hide ParametersShow Parameters

:AWS

:AWS_PRO_SERVICE

:GCP

:GCP_PRO_SERVICE

scheduled_charge_custom_fieldshash

optional

Hash[Symbol, String]

scheduled_charge_idString

optional

ID of scheduled charge.

formatuuid

starting_atTime

optional

The line item's start date (inclusive).

formatdate-time

sub_line_itemsarray

optional

Array[{ custom_fields, name, quantity, 8 more}]

Hide ParametersShow Parameters

custom_fieldshash

Hash[Symbol, String]

nameString

quantityFloat

subtotalFloat

charge_idString

optional

formatuuid

credit_grant_idString

optional

formatuuid

end_dateTime

optional

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

formatdate-time

priceFloat

optional

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

start_dateTime

optional

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

formatdate-time

tier_periodobject

optional

{ starting_at, ending_before}

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

Hide ParametersShow Parameters

starting_atTime

formatdate-time

ending_beforeTime

optional

formatdate-time

tiersarray

optional

Array[{ price, quantity, starting_at, subtotal}]

Hide ParametersShow Parameters

priceFloat

quantityFloat

starting_atFloat

at what metric amount this tier begins

subtotalFloat

subscription_custom_fieldshash

optional

Hash[Symbol, String]

tierobject

optional

{ level, starting_at, size}

Populated if the line item has a tiered price.

Hide ParametersShow Parameters

levelFloat

starting_atString

sizeString

optional

unit_priceFloat

optional

The unit price associated with the line item.

statusString

totalFloat

typeString

amendment_idString

optional

formatuuid

billable_statusunion

optional

:billable | :unbillable

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

Hide ParametersShow Parameters

:billable

:unbillable

contract_custom_fieldshash

optional

Hash[Symbol, String]

contract_idString

optional

formatuuid

correction_recordobject

optional

{ corrected_invoice_id, memo, reason, corrected_external_invoice}

Hide ParametersShow Parameters

corrected_invoice_idString

formatuuid

memoString

reasonString

corrected_external_invoiceobject

optional

{ billing_provider_type, external_status, invoice_id, issued_at_timestamp}

Hide ParametersShow Parameters

billing_provider_typeunion

:aws_marketplace | :stripe | :netsuite | 5 more

Hide ParametersShow Parameters

:aws_marketplace

:stripe

:netsuite

:custom

:azure_marketplace

:quickbooks_online

:workday

:gcp_marketplace

external_statusunion

optional

:DRAFT | :FINALIZED | :PAID | 8 more

Hide ParametersShow Parameters

:DRAFT

:FINALIZED

:PAID

:UNCOLLECTIBLE

:VOID

:DELETED

:PAYMENT_FAILED

:INVALID_REQUEST_ERROR

:SKIPPED

:SENT

:QUEUED

invoice_idString

optional

issued_at_timestampTime

optional

formatdate-time

created_atTime

optional

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

formatdate-time

custom_fieldshash

optional

Hash[Symbol, untyped]

customer_custom_fieldshash

optional

Hash[Symbol, String]

end_timestampTime

optional

End of the usage period this invoice covers (UTC)

formatdate-time

external_invoiceobject

optional

{ billing_provider_type, external_status, invoice_id, issued_at_timestamp}

Hide ParametersShow Parameters

billing_provider_typeunion

:aws_marketplace | :stripe | :netsuite | 5 more

Hide ParametersShow Parameters

:aws_marketplace

:stripe

:netsuite

:custom

:azure_marketplace

:quickbooks_online

:workday

:gcp_marketplace

external_statusunion

optional

:DRAFT | :FINALIZED | :PAID | 8 more

Hide ParametersShow Parameters

:DRAFT

:FINALIZED

:PAID

:UNCOLLECTIBLE

:VOID

:DELETED

:PAYMENT_FAILED

:INVALID_REQUEST_ERROR

:SKIPPED

:SENT

:QUEUED

invoice_idString

optional

issued_at_timestampTime

optional

formatdate-time

invoice_adjustmentsarray

optional

Array[{ credit_type, name, total, 2 more}]

Hide ParametersShow Parameters

credit_typeidStringnameStringCreditTypeData

nameString

totalFloat

credit_grant_custom_fieldshash

optional

Hash[Symbol, String]

credit_grant_idString

optional

issued_atTime

optional

When the invoice was issued (UTC)

formatdate-time

net_payment_terms_daysFloat

optional

netsuite_sales_order_idString

optional

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

plan_custom_fieldshash

optional

Hash[Symbol, String]

plan_idString

optional

formatuuid

plan_nameString

optional

reseller_royaltyobject

optional

{ fraction, netsuite_reseller_id, reseller_type, 2 more}

Only present for contract invoices with reseller royalties.

Hide ParametersShow Parameters

fractionString

netsuite_reseller_idString

reseller_typeunion

:AWS | :AWS_PRO_SERVICE | :GCP | :GCP_PRO_SERVICE

Hide ParametersShow Parameters

:AWS

:AWS_PRO_SERVICE

:GCP

:GCP_PRO_SERVICE

aws_optionsobject

optional

{ aws_account_number, aws_offer_id, aws_payer_reference_id}

Hide ParametersShow Parameters

aws_account_numberString

optional

aws_offer_idString

optional

aws_payer_reference_idString

optional

gcp_optionsobject

optional

{ gcp_account_id, gcp_offer_id}

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_timestampTime

optional

Beginning of the usage period this invoice covers (UTC)

formatdate-time

subtotalFloat

optional

CustomersNamed Schedules

Get a customer's named schedule

v1.customers.named_schedules.retrieve(**kwargs) -> dataarrayNamedScheduleRetrieveResponse

post/v1/customers/getNamedSchedule

Update a customer's named schedule

v1.customers.named_schedules.update(**kwargs) -> void

post/v1/customers/updateNamedSchedule

CustomersPlans

Add a plan to a customer

v1.customers.plans.add(**kwargs) -> dataIDPlanAddResponse

post/v1/customers/{customer_id}/plans/add

End a customer plan

v1.customers.plans.end_(**kwargs) -> PlanEndResponse

post/v1/customers/{customer_id}/plans/{customer_plan_id}/end

List customer plans

v1.customers.plans.list(**kwargs) -> CursorPage<idStringcustom_fieldshashplan_descriptionStringplan_idStringplan_nameStringstarting_onTimeending_beforeTimenet_payment_terms_daysFloattrial_infoobjectPlanListResponse>

get/v1/customers/{customer_id}/plans

Get the plan adjustments for a customer

v1.customers.plans.list_price_adjustments(**kwargs) -> CursorPage<charge_idStringcharge_typeunionpricesarraystart_periodFloatquantityFloatPlanListPriceAdjustmentsResponse>

get/v1/customers/{customer_id}/plans/{customer_plan_id}/priceAdjustments