# Plans

## List

`v1.plans.list(PlanListParams**kwargs)  -> SyncCursorPage[PlanListResponse]`

**get** `/v1/plans`

List all available plans.

### Parameters

- **limit:** `int`

  Max number of results that should be returned

- **next\_page:** `str`

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

### Returns

- `class PlanListResponse`

  - **id:** `str`

  - **description:** `str`

  - **name:** `str`

  - **custom\_fields:** `Optional[Dict[str, str]]`

### Example

```python
from metronome import Metronome

client = Metronome(
    bearer_token="My Bearer Token",
)
page = client.v1.plans.list()
page = page.data[0]
print(page.id)
```

## Get Details

`v1.plans.get_details(PlanGetDetailsParams**kwargs)  -> PlanGetDetailsResponse`

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

Fetch high level details of a specific plan.

### Parameters

- **plan\_id:** `str`

### Returns

- `class PlanGetDetailsResponse`

  - **data:** `PlanDetail`

### Example

```python
from metronome import Metronome

client = Metronome(
    bearer_token="My Bearer Token",
)
response = client.v1.plans.get_details(
    plan_id="d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc",
)
print(response.data)
```

## List Charges

`v1.plans.list_charges(PlanListChargesParams**kwargs)  -> SyncCursorPage[PlanListChargesResponse]`

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

Fetches a list of charges of a specific plan.

### Parameters

- **plan\_id:** `str`

- **limit:** `int`

  Max number of results that should be returned

- **next\_page:** `str`

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

### Returns

- `class PlanListChargesResponse`

  - **id:** `str`

  - **charge\_type:** `Literal["usage", "fixed", "composite", 2 more]`

    - `"usage"`

    - `"fixed"`

    - `"composite"`

    - `"minimum"`

    - `"seat"`

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

  - **custom\_fields:** `Dict[str, str]`

  - **name:** `str`

  - **prices:** `List[Price]`

    - **tier:** `float`

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

    - **value:** `float`

    - **collection\_interval:** `Optional[float]`

    - **collection\_schedule:** `Optional[str]`

    - **quantity:** `Optional[float]`

  - **product\_id:** `str`

  - **product\_name:** `str`

  - **quantity:** `Optional[float]`

  - **start\_period:** `Optional[float]`

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

  - **tier\_reset\_frequency:** `Optional[float]`

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

  - **unit\_conversion:** `Optional[UnitConversion]`

    Specifies how quantities for usage based charges will be converted.

    - **division\_factor:** `float`

      The conversion factor

    - **rounding\_behavior:** `Optional[Literal["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

```python
from metronome import Metronome

client = Metronome(
    bearer_token="My Bearer Token",
)
page = client.v1.plans.list_charges(
    plan_id="d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc",
)
page = page.data[0]
print(page.id)
```

## List Customers

`v1.plans.list_customers(PlanListCustomersParams**kwargs)  -> SyncCursorPage[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

- **plan\_id:** `str`

- **limit:** `int`

  Max number of results that should be returned

- **next\_page:** `str`

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

- **status:** `Literal["all", "active", "ended", "upcoming"]`

  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

- `class PlanListCustomersResponse`

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

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

    - **id:** `str`

    - **custom\_fields:** `Dict[str, str]`

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

    - **name:** `str`

    - **starting\_on:** `datetime`

      The start date of the plan

    - **ending\_before:** `Optional[datetime]`

      The end date of the plan

### Example

```python
from metronome import Metronome

client = Metronome(
    bearer_token="My Bearer Token",
)
page = client.v1.plans.list_customers(
    plan_id="d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc",
)
page = page.data[0]
print(page.customer_details)
```

## Domain Types

### Plan Detail

- `class PlanDetail`

  - **id:** `str`

  - **custom\_fields:** `Dict[str, str]`

  - **name:** `str`

  - **credit\_grants:** `Optional[List[CreditGrant]]`

    - **amount\_granted:** `float`

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

    - **amount\_paid:** `float`

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

    - **effective\_duration:** `float`

    - **name:** `str`

    - **priority:** `str`

    - **send\_invoice:** `bool`

    - **reason:** `Optional[str]`

    - **recurrence\_duration:** `Optional[float]`

    - **recurrence\_interval:** `Optional[float]`

  - **description:** `Optional[str]`

  - **minimums:** `Optional[List[Minimum]]`

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

    - **name:** `str`

    - **start\_period:** `float`

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

    - **value:** `float`

  - **overage\_rates:** `Optional[List[OverageRate]]`

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

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

    - **start\_period:** `float`

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

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