# Customers

## Create

`client.v1.customers.create(CustomerCreateParamsbody, RequestOptionsoptions?): CustomerCreateResponse`

**post** `/v1/customers`

Create a new customer

### Parameters

- **body:** `CustomerCreateParams`

  - **name:** `string`

    This will be truncated to 160 characters if the provided name is longer.

  - **billing\_config:** `BillingConfig`

    - **billing\_provider\_customer\_id:** `string`

    - **billing\_provider\_type:** `"aws_marketplace" | "stripe" | "netsuite" | 5 more`

      - `"aws_marketplace"`

      - `"stripe"`

      - `"netsuite"`

      - `"custom"`

      - `"azure_marketplace"`

      - `"quickbooks_online"`

      - `"workday"`

      - `"gcp_marketplace"`

    - **aws\_is\_subscription\_product:** `boolean`

      True if the aws_product_code is a SAAS subscription product, false otherwise.

    - **aws\_product\_code:** `string`

    - **aws\_region:** `"af-south-1" | "ap-east-1" | "ap-northeast-1" | 22 more`

      - `"af-south-1"`

      - `"ap-east-1"`

      - `"ap-northeast-1"`

      - `"ap-northeast-2"`

      - `"ap-northeast-3"`

      - `"ap-south-1"`

      - `"ap-southeast-1"`

      - `"ap-southeast-2"`

      - `"ca-central-1"`

      - `"cn-north-1"`

      - `"cn-northwest-1"`

      - `"eu-central-1"`

      - `"eu-north-1"`

      - `"eu-south-1"`

      - `"eu-west-1"`

      - `"eu-west-2"`

      - `"eu-west-3"`

      - `"me-south-1"`

      - `"sa-east-1"`

      - `"us-east-1"`

      - `"us-east-2"`

      - `"us-gov-east-1"`

      - `"us-gov-west-1"`

      - `"us-west-1"`

      - `"us-west-2"`

    - **stripe\_collection\_method:** `"charge_automatically" | "send_invoice"`

      - `"charge_automatically"`

      - `"send_invoice"`

  - **custom\_fields:** `Record<string, string>`

  - **customer\_billing\_provider\_configurations:** `Array<CustomerBillingProviderConfiguration>`

    - **billing\_provider:** `"aws_marketplace" | "azure_marketplace" | "gcp_marketplace" | 2 more`

      The billing provider set for this configuration.

      - `"aws_marketplace"`

      - `"azure_marketplace"`

      - `"gcp_marketplace"`

      - `"stripe"`

      - `"netsuite"`

    - **configuration:** `Record<string, unknown>`

      Configuration for the billing provider. The structure of this object is specific to the billing provider and delivery provider combination. Defaults to an empty object, however, for most billing provider + delivery method combinations, it will not be a valid configuration.

    - **delivery\_method:** `"direct_to_billing_provider" | "aws_sqs" | "tackle" | "aws_sns"`

      The method to use for delivering invoices to this customer. If not provided, the `delivery_method_id` must be provided.

      - `"direct_to_billing_provider"`

      - `"aws_sqs"`

      - `"tackle"`

      - `"aws_sns"`

    - **delivery\_method\_id:** `string`

      ID of the delivery method to use for this customer. If not provided, the `delivery_method` must be provided.

  - **external\_id:** `string`

    (deprecated, use ingest_aliases instead) an alias that can be used to refer to this customer in usage events

  - **ingest\_aliases:** `Array<string>`

    Aliases that can be used to refer to this customer in usage events

### Returns

- `CustomerCreateResponse`
  - **data:** `Customer`

### Example

```node
import Metronome from '@metronome/sdk';

const client = new Metronome({
  bearerToken: 'My Bearer Token',
});

const customer = await client.v1.customers.create({
  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' },
    },
  ],
  ingest_aliases: ['team@example.com'],
});

console.log(customer.data);
```

## Retrieve

`client.v1.customers.retrieve(CustomerRetrieveParamsparams, RequestOptionsoptions?): CustomerRetrieveResponse`

**get** `/v1/customers/{customer_id}`

Get a customer by Metronome ID.

### Parameters

- **params:** `CustomerRetrieveParams`

  - **customer\_id:** `string`

### Returns

- `CustomerRetrieveResponse`
  - **data:** `CustomerDetail`

### Example

```node
import Metronome from '@metronome/sdk';

const client = new Metronome({
  bearerToken: 'My Bearer Token',
});

const customer = await client.v1.customers.retrieve({ customer_id: 'd7abd0cd-4ae9-4db7-8676-e986a4ebd8dc' });

console.log(customer.data);
```

## List

`client.v1.customers.list(CustomerListParamsquery?, RequestOptionsoptions?): CursorPage<CustomerDetail>`

**get** `/v1/customers`

List all customers.

### Parameters

- **query:** `CustomerListParams`

  - **customer\_ids:** `Array<string>`

    Filter the customer list by customer_id.  Up to 100 ids can be provided.

  - **ingest\_alias:** `string`

    Filter the customer list by ingest_alias

  - **limit:** `number`

    Max number of results that should be returned

  - **next\_page:** `string`

    Cursor that indicates where the next page of results should start.

  - **only\_archived:** `boolean`

    Filter the customer list to only return archived customers. By default, only active customers are returned.

  - **salesforce\_account\_ids:** `Array<string>`

    Filter the customer list by salesforce_account_id.  Up to 100 ids can be provided.

### Returns

- `CustomerDetail`

### Example

```node
import Metronome from '@metronome/sdk';

const client = new Metronome({
  bearerToken: 'My Bearer Token',
});

// Automatically fetches more pages as needed.
for await (const customerDetail of client.v1.customers.list()) {
  console.log(customerDetail.id);
}
```

## Archive

`client.v1.customers.archive(CustomerArchiveParamsbody, RequestOptionsoptions?): CustomerArchiveResponse`

**post** `/v1/customers/archive`

Archive a customer Note: any alerts associated with the customer will not be triggered.

### Parameters

- **body:** `CustomerArchiveParams`

  - **id:** `string`

### Returns

- `CustomerArchiveResponse`
  - **data:** `ID`

### Example

```node
import Metronome from '@metronome/sdk';

const client = new Metronome({
  bearerToken: 'My Bearer Token',
});

const response = await client.v1.customers.archive({ id: '8deed800-1b7a-495d-a207-6c52bac54dc9' });

console.log(response.data);
```

## List Billable Metrics

`client.v1.customers.listBillableMetrics(CustomerListBillableMetricsParamsparams, RequestOptionsoptions?): CursorPage<CustomerListBillableMetricsResponse>`

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

Get all billable metrics for a given customer.

### Parameters

- **params:** `CustomerListBillableMetricsParams`

  - **customer\_id:** `string`

    Path param:

  - **include\_archived:** `boolean`

    Query param: If true, the list of returned metrics will include archived metrics

  - **limit:** `number`

    Query param: Max number of results that should be returned

  - **next\_page:** `string`

    Query param: Cursor that indicates where the next page of results should start.

  - **on\_current\_plan:** `boolean`

    Query param: If true, the list of metrics will be filtered to just ones that are on the customer's current plan

### Returns

- `CustomerListBillableMetricsResponse`
  - **id:** `string`

  - **name:** `string`

  - **aggregate:** `string`

    (DEPRECATED) use aggregation_type instead

  - **aggregate\_keys:** `Array<string>`

    (DEPRECATED) use aggregation_key instead

  - **aggregation\_key:** `string`

    A key that specifies which property of the event is used to aggregate data. This key must be one of the property filter names and is not applicable when the aggregation type is 'count'.

  - **aggregation\_type:** `"COUNT" | "LATEST" | "MAX" | 2 more`

    Specifies the type of aggregation performed on matching events.

    - `"COUNT"`

    - `"LATEST"`

    - `"MAX"`

    - `"SUM"`

    - `"UNIQUE"`

  - **archived\_at:** `string`

    RFC 3339 timestamp indicating when the billable metric was archived. If not provided, the billable metric is not archived.

  - **custom\_fields:** `Record<string, string>`

  - **event\_type\_filter:** `EventTypeFilter`

    An optional filtering rule to match the 'event_type' property of an event.

  - **filter:** `Record<string, unknown>`

    (DEPRECATED) use property_filters & event_type_filter instead

  - **group\_by:** `Array<string>`

    (DEPRECATED) use group_keys instead

  - **group\_keys:** `Array<Array<string>>`

    Property names that are used to group usage costs on an invoice. Each entry represents a set of properties used to slice events into distinct buckets.

  - **property\_filters:** `Array<PropertyFilter>`

    A list of filters to match events to this billable metric. Each filter defines a rule on an event property. All rules must pass for the event to match the billable metric.

    - **name:** `string`

      The name of the event property.

    - **exists:** `boolean`

      Determines whether the property must exist in the event. If true, only events with this property will pass the filter. If false, only events without this property will pass the filter. If null or omitted, the existence of the property is optional.

    - **in\_values:** `Array<string>`

      Specifies the allowed values for the property to match an event. An event will pass the filter only if its property value is included in this list. If undefined, all property values will pass the filter. Must be non-empty if present.

    - **not\_in\_values:** `Array<string>`

      Specifies the values that prevent an event from matching the filter. An event will not pass the filter if its property value is included in this list. If null or empty, all property values will pass the filter. Must be non-empty if present.

  - **sql:** `string`

    The SQL query associated with the billable metric

### Example

```node
import Metronome from '@metronome/sdk';

const client = new Metronome({
  bearerToken: 'My Bearer Token',
});

// Automatically fetches more pages as needed.
for await (const customerListBillableMetricsResponse of client.v1.customers.listBillableMetrics({
  customer_id: 'd7abd0cd-4ae9-4db7-8676-e986a4ebd8dc',
})) {
  console.log(customerListBillableMetricsResponse.id);
}
```

## List Costs

`client.v1.customers.listCosts(CustomerListCostsParamsparams, RequestOptionsoptions?): CursorPage<CustomerListCostsResponse>`

**get** `/v1/customers/{customer_id}/costs`

Fetch daily pending costs for the specified customer, broken down by credit type and line items. Note: this is not supported for customers whose plan includes a UNIQUE-type billable metric.

### Parameters

- **params:** `CustomerListCostsParams`

  - **customer\_id:** `string`

    Path param:

  - **ending\_before:** `string`

    Query param: RFC 3339 timestamp (exclusive)

  - **starting\_on:** `string`

    Query param: RFC 3339 timestamp (inclusive)

  - **limit:** `number`

    Query param: Max number of results that should be returned

  - **next\_page:** `string`

    Query param: Cursor that indicates where the next page of results should start.

### Returns

- `CustomerListCostsResponse`
  - **credit\_types:** `Record<string, CreditTypes>`

    - **cost:** `number`

    - **line\_item\_breakdown:** `Array<LineItemBreakdown>`

      - **cost:** `number`

      - **name:** `string`

      - **group\_key:** `string`

      - **group\_value:** `string | null`

    - **name:** `string`

  - **end\_timestamp:** `string`

  - **start\_timestamp:** `string`

### Example

```node
import Metronome from '@metronome/sdk';

const client = new Metronome({
  bearerToken: 'My Bearer Token',
});

// Automatically fetches more pages as needed.
for await (const customerListCostsResponse of client.v1.customers.listCosts({
  customer_id: 'd7abd0cd-4ae9-4db7-8676-e986a4ebd8dc',
  ending_before: '2019-12-27T18:11:19.117Z',
  starting_on: '2019-12-27T18:11:19.117Z',
})) {
  console.log(customerListCostsResponse.credit_types);
}
```

## Preview Events

`client.v1.customers.previewEvents(CustomerPreviewEventsParamsparams, RequestOptionsoptions?): CustomerPreviewEventsResponse`

**post** `/v1/customers/{customer_id}/previewEvents`

Preview how a set of events will affect a customer's invoice. Generates a draft invoice for a customer using their current contract configuration and the provided events. This is useful for testing how new events will affect the customer's invoice before they are actually processed.

### Parameters

- **params:** `CustomerPreviewEventsParams`

  - **customer\_id:** `string`

    Path param:

  - **events:** `Array<Event>`

    Body param:

    - **event\_type:** `string`

    - **customer\_id:** `string`

      This has no effect for preview events, but may be set for consistency with Event objects. They will be processed even if they do not match the customer's ID or ingest aliases.

    - **properties:** `Record<string, unknown>`

    - **timestamp:** `string`

      RFC 3339 formatted. If not provided, the current time will be used.

    - **transaction\_id:** `string`

      This has no effect for preview events, but may be set for consistency with Event objects. Duplicate transaction_ids are NOT filtered out, even within the same request.

  - **mode:** `"replace" | "merge"`

    Body param: If set to "replace", the preview will be generated as if those were the only events for the specified customer. If set to "merge", the events will be merged with any existing events for the specified customer. Defaults to "replace".

    - `"replace"`

    - `"merge"`

  - **skip\_zero\_qty\_line\_items:** `boolean`

    Body param: If set, all zero quantity line items will be filtered out of the response.

### Returns

- `CustomerPreviewEventsResponse`
  - **data:** `Invoice`

### Example

```node
import Metronome from '@metronome/sdk';

const client = new Metronome({
  bearerToken: 'My Bearer Token',
});

const response = await client.v1.customers.previewEvents({
  customer_id: 'd7abd0cd-4ae9-4db7-8676-e986a4ebd8dc',
  events: [
    {
      event_type: 'heartbeat',
      timestamp: '2021-01-01T00:00:00Z',
      properties: { cpu_hours: 100, memory_gb_hours: 200 },
    },
  ],
});

console.log(response.data);
```

## Set Ingest Aliases

`client.v1.customers.setIngestAliases(CustomerSetIngestAliasesParamsparams, RequestOptionsoptions?): void`

**post** `/v1/customers/{customer_id}/setIngestAliases`

Sets the ingest aliases for a customer. Ingest aliases can be used in the `customer_id` field when sending usage events to Metronome. This call is idempotent. It fully replaces the set of ingest aliases for the given customer.

### Parameters

- **params:** `CustomerSetIngestAliasesParams`

  - **customer\_id:** `string`

    Path param:

  - **ingest\_aliases:** `Array<string>`

    Body param:

### Example

```node
import Metronome from '@metronome/sdk';

const client = new Metronome({
  bearerToken: 'My Bearer Token',
});

await client.v1.customers.setIngestAliases({
  customer_id: 'd7abd0cd-4ae9-4db7-8676-e986a4ebd8dc',
  ingest_aliases: ['team@example.com'],
});
```

## Set Name

`client.v1.customers.setName(CustomerSetNameParamsparams, RequestOptionsoptions?): CustomerSetNameResponse`

**post** `/v1/customers/{customer_id}/setName`

Updates the specified customer's name.

### Parameters

- **params:** `CustomerSetNameParams`

  - **customer\_id:** `string`

    Path param:

  - **name:** `string`

    Body param: The new name for the customer. This will be truncated to 160 characters if the provided name is longer.

### Returns

- `CustomerSetNameResponse`
  - **data:** `Customer`

### Example

```node
import Metronome from '@metronome/sdk';

const client = new Metronome({
  bearerToken: 'My Bearer Token',
});

const response = await client.v1.customers.setName({
  customer_id: 'd7abd0cd-4ae9-4db7-8676-e986a4ebd8dc',
  name: 'Example, Inc.',
});

console.log(response.data);
```

## Update Config

`client.v1.customers.updateConfig(CustomerUpdateConfigParamsparams, RequestOptionsoptions?): void`

**post** `/v1/customers/{customer_id}/updateConfig`

Updates the specified customer's config.

### Parameters

- **params:** `CustomerUpdateConfigParams`

  - **customer\_id:** `string`

    Path param:

  - **leave\_stripe\_invoices\_in\_draft:** `boolean | null`

    Body param: Leave in draft or set to auto-advance on invoices sent to Stripe. Falls back to the client-level config if unset, which defaults to true if unset.

  - **salesforce\_account\_id:** `string | null`

    Body param: The Salesforce account ID for the customer

### Example

```node
import Metronome from '@metronome/sdk';

const client = new Metronome({
  bearerToken: 'My Bearer Token',
});

await client.v1.customers.updateConfig({
  customer_id: 'd7abd0cd-4ae9-4db7-8676-e986a4ebd8dc',
  salesforce_account_id: '0015500001WO1ZiABL',
});
```

## Domain Types

### Customer

- `Customer`
  - **id:** `string`

    the Metronome ID of the customer

  - **external\_id:** `string`

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

  - **ingest\_aliases:** `Array<string>`

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

  - **name:** `string`

  - **custom\_fields:** `Record<string, string>`

### Customer Detail

- `CustomerDetail`
  - **id:** `string`

    the Metronome ID of the customer

  - **created\_at:** `string`

    RFC 3339 timestamp indicating when the customer was created.

  - **custom\_fields:** `Record<string, string>`

  - **customer\_config:** `CustomerConfig`

    - **salesforce\_account\_id:** `string | null`

      The Salesforce account ID for the customer

  - **external\_id:** `string`

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

  - **ingest\_aliases:** `Array<string>`

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

  - **name:** `string`

  - **archived\_at:** `string | null`

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

  - **current\_billable\_status:** `CurrentBillableStatus`

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

    - **value:** `"billable" | "unbillable"`

      - `"billable"`

      - `"unbillable"`

    - **effective\_at:** `string | null`