# Plans

## List

`client.v1.plans.list(PlanListParamsquery?, RequestOptionsoptions?): CursorPage<PlanListResponse>`

**get** `/v1/plans`

List all available plans.

### Parameters

- **query:** `PlanListParams`

  - **limit:** `number`

    Max number of results that should be returned

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

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

### Returns

- `PlanListResponse`
  - **id:** `string`

  - **description:** `string`

  - **name:** `string`

  - **custom\_fields:** `Record<string, 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 planListResponse of client.v1.plans.list()) {
  console.log(planListResponse.id);
}
```

## Get Details

`client.v1.plans.getDetails(PlanGetDetailsParamsparams, RequestOptionsoptions?): PlanGetDetailsResponse`

**get** `/v1/planDetails/{plan_id}`

Fetch high level details of a specific plan.

### Parameters

- **params:** `PlanGetDetailsParams`

  - **plan\_id:** `string`

### Returns

- `PlanGetDetailsResponse`
  - **data:** `PlanDetail`

### Example

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

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

const response = await client.v1.plans.getDetails({ plan_id: 'd7abd0cd-4ae9-4db7-8676-e986a4ebd8dc' });

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

## List Charges

`client.v1.plans.listCharges(PlanListChargesParamsparams, RequestOptionsoptions?): CursorPage<PlanListChargesResponse>`

**get** `/v1/planDetails/{plan_id}/charges`

Fetches a list of charges of a specific plan.

### Parameters

- **params:** `PlanListChargesParams`

  - **plan\_id:** `string`

    Path param:

  - **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

- `PlanListChargesResponse`
  - **id:** `string`

  - **charge\_type:** `"usage" | "fixed" | "composite" | 2 more`

    - `"usage"`

    - `"fixed"`

    - `"composite"`

    - `"minimum"`

    - `"seat"`

  - **credit\_type:** `CreditTypeData`

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

  - **name:** `string`

  - **prices:** `Array<Price>`

    - **tier:** `number`

      Used in pricing tiers.  Indicates at what metric value the price applies.

    - **value:** `number`

    - **collection\_interval:** `number`

    - **collection\_schedule:** `string`

    - **quantity:** `number`

  - **product\_id:** `string`

  - **product\_name:** `string`

  - **quantity:** `number`

  - **start\_period:** `number`

    Used in price ramps.  Indicates how many billing periods pass before the charge applies.

  - **tier\_reset\_frequency:** `number`

    Used in pricing tiers.  Indicates how often the tier resets. Default is 1 - the tier count resets every billing period.

  - **unit\_conversion:** `UnitConversion`

    Specifies how quantities for usage based charges will be converted.

    - **division\_factor:** `number`

      The conversion factor

    - **rounding\_behavior:** `"floor" | "ceiling"`

      Whether usage should be rounded down or up to the nearest whole number. If null, quantity will be rounded to 20 decimal places.

      - `"floor"`

      - `"ceiling"`

### Example

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

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

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

## List Customers

`client.v1.plans.listCustomers(PlanListCustomersParamsparams, RequestOptionsoptions?): CursorPage<PlanListCustomersResponse>`

**get** `/v1/planDetails/{plan_id}/customers`

Fetches a list of customers on a specific plan (by default, only currently active plans are included)

### Parameters

- **params:** `PlanListCustomersParams`

  - **plan\_id:** `string`

    Path param:

  - **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.

  - **status:** `"all" | "active" | "ended" | "upcoming"`

    Query param: Status of customers on a given plan. Defaults to `active`.

    * `all` - Return current, past, and upcoming customers of the plan.
    * `active` - Return current customers of the plan.
    * `ended` - Return past customers of the plan.
    * `upcoming` - Return upcoming customers of the plan.

    Multiple statuses can be OR'd together using commas, e.g. `active,ended`.
    **Note:** `ended,upcoming` combination is not yet supported.

    - `"all"`

    - `"active"`

    - `"ended"`

    - `"upcoming"`

### Returns

- `PlanListCustomersResponse`
  - **customer\_details:** `CustomerDetail`

  - **plan\_details:** `PlanDetails`

    - **id:** `string`

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

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

    - **name:** `string`

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

      The start date of the plan

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

      The end date of the plan

### Example

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

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

// Automatically fetches more pages as needed.
for await (const planListCustomersResponse of client.v1.plans.listCustomers({
  plan_id: 'd7abd0cd-4ae9-4db7-8676-e986a4ebd8dc',
})) {
  console.log(planListCustomersResponse.customer_details);
}
```

## Domain Types

### Plan Detail

- `PlanDetail`
  - **id:** `string`

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

  - **name:** `string`

  - **credit\_grants:** `Array<CreditGrant>`

    - **amount\_granted:** `number`

    - **amount\_granted\_credit\_type:** `CreditTypeData`

    - **amount\_paid:** `number`

    - **amount\_paid\_credit\_type:** `CreditTypeData`

    - **effective\_duration:** `number`

    - **name:** `string`

    - **priority:** `string`

    - **send\_invoice:** `boolean`

    - **reason:** `string`

    - **recurrence\_duration:** `number`

    - **recurrence\_interval:** `number`

  - **description:** `string`

  - **minimums:** `Array<Minimum>`

    - **credit\_type:** `CreditTypeData`

    - **name:** `string`

    - **start\_period:** `number`

      Used in price ramps.  Indicates how many billing periods pass before the charge applies.

    - **value:** `number`

  - **overage\_rates:** `Array<OverageRate>`

    - **credit\_type:** `CreditTypeData`

    - **fiat\_credit\_type:** `CreditTypeData`

    - **start\_period:** `number`

      Used in price ramps.  Indicates how many billing periods pass before the charge applies.

    - **to\_fiat\_conversion\_factor:** `number`