# Retrieve billing information with Viam's billing client API

The billing client allows you to retrieve billing information from Viam.

The billing API supports the following methods:

| Method Name | Description |
| --- | --- |
| [`GetCurrentMonthUsage`](https://docs.viam.com/reference/apis/billing-client/#getcurrentmonthusage) | Access data usage information for the current billing period for a given organization. |
| [`GetOrgBillingInformation`](https://docs.viam.com/reference/apis/billing-client/#getorgbillinginformation) | Access billing information (payment method, billing tier, etc.) for a given org. |
| [`GetInvoicesSummary`](https://docs.viam.com/reference/apis/billing-client/#getinvoicessummary) | Access total outstanding balance plus invoice summaries for a given organization. |
| [`GetInvoicePDF`](https://docs.viam.com/reference/apis/billing-client/#getinvoicepdf) | Access invoice PDF data and optionally save it to a provided file path. |
| [`CreateInvoiceAndChargeImmediately`](https://docs.viam.com/reference/apis/billing-client/#createinvoiceandchargeimmediately) | Create a flat fee invoice and charge the organization immediately. The caller must be an owner of the organization being charged. This function blocks until payment is confirmed, but will time out after 2 minutes if there is no confirmation. |
| [`ChargeOrganization`](https://docs.viam.com/reference/apis/billing-client/#chargeorganization) | Charge an organization for usage.

## Establish a connection

To use the billing client API, you need to instantiate a `ViamClient` and then instantiate a `BillingClient`.

You need an API key and API key ID with [Org owner permissions](https://docs.viam.com/organization/rbac/#organization-settings-and-roles) to use the billing client API. To get an API key (and corresponding ID), use the [web UI](https://docs.viam.com/organization/api-keys/#create-an-api-key) to the [Viam CLI](https://docs.viam.com/cli/).

- [From a client application](https://docs.viam.com/reference/apis/billing-client/#tabset-referenceapisbilling-client-2-0)
- [From within a Module](https://docs.viam.com/reference/apis/billing-client/#tabset-referenceapisbilling-client-2-1)

- [Python](https://docs.viam.com/reference/apis/billing-client/#tabset-referenceapisbilling-client-1-0)
- [Go](https://docs.viam.com/reference/apis/billing-client/#tabset-referenceapisbilling-client-1-1)
- [TypeScript](https://docs.viam.com/reference/apis/billing-client/#tabset-referenceapisbilling-client-1-2)

```python

```

Copy

```go

```

Copy

```ts

```

Copy

Once you have instantiated a `BillingClient`, you can run [API methods](https://docs.viam.com/reference/apis/billing-client/#api) against the `BillingClient` object (named `billing_client` in the examples).

## API

### GetCurrentMonthUsage

Access data usage information for the current billing period for a given organization. This method only returns usage for organizations with monthly billing at the end of the month (`"in_arrears": true`). You can also find your usage data on the [**Payment and billing** page](https://docs.viam.com/organization/billing/).

**Parameters:**

- `org_id` ( [str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str)) (required): the ID of the organization to request usage data for.
- `timeout` ( [float](https://docs.python.org/3/library/stdtypes.html#numeric-types-int-float-complex)) (optional): An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call.

**Returns:**

- ( [viam.proto.app.billing.GetCurrentMonthUsageResponse](https://python.viam.dev/autoapi/viam/proto/app/billing/index.html#viam.proto.app.billing.GetCurrentMonthUsageResponse)): : the current month usage information.

**Example:**

```python

```

Copy

For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/app/billing_client/index.html#viam.app.billing_client.BillingClient.get_current_month_usage).

### GetOrgBillingInformation

Access billing information (payment method, billing tier, etc.) for a given org. You can also find this information on the [**Payment and billing** page](https://docs.viam.com/organization/billing/).

**Parameters:**

- `org_id` ( [str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str)) (required): the ID of the organization to request data for.
- `timeout` ( [float](https://docs.python.org/3/library/stdtypes.html#numeric-types-int-float-complex)) (optional): An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call.

**Returns:**

- ( [viam.proto.app.billing.GetOrgBillingInformationResponse](https://python.viam.dev/autoapi/viam/proto/app/billing/index.html#viam.proto.app.billing.GetOrgBillingInformationResponse)): : the organization billing information.

### GetInvoicesSummary

Access total outstanding balance plus invoice summaries for a given organization. This includes both monthly and annual invoices depending on the organization’s billing configuration.

**Parameters:**

**Returns:**

- ( [viam.proto.app.billing.GetInvoicesSummaryResponse](https://python.viam.dev/autoapi/viam/proto/app/billing/index.html#viam.proto.app.billing.GetInvoicesSummaryResponse)): : the summaries of all organization invoices.

### GetInvoicePDF

Access invoice PDF data and optionally save it to a provided file path. You can also find your invoices on the [**Payment and billing** page](https://docs.viam.com/organization/billing/).

**Parameters:**

- `invoice_id` ( [str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str)) (required): the ID of the invoice being requested.
- `org_id` ( [str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str)) (required): the ID of the organization to request data from.
- `dest` ( [str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str)) (required): the filepath to save the invoice to.
- `timeout` ( [float](https://docs.python.org/3/library/stdtypes.html#numeric-types-int-float-complex)) (optional): An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call.

**Returns:**

- None.

### CreateInvoiceAndChargeImmediately

Create a flat fee invoice and charge the organization immediately. The caller must be an owner of the organization being charged. This function blocks until payment is confirmed, but will time out after 2 minutes if there is no confirmation.

**Parameters:**

- `org_id_to_charge` ( [str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str)) (required)
- `amount` ( [float](https://docs.python.org/3/library/stdtypes.html#numeric-types-int-float-complex)) (required)
- `description` ( [str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str)) (optional)
- `org_id_for_branding` ( [str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str)) (optional)
- `disable_email` ( [bool](https://docs.python.org/3/library/stdtypes.html#boolean-type-bool)) (required)

**Returns:**

- ( [viam.proto.app.billing.CreateInvoiceAndChargeImmediatelyResponse](https://python.viam.dev/autoapi/viam/proto/app/billing/index.html#viam.proto.app.billing.CreateInvoiceAndChargeImmediatelyResponse))

### ChargeOrganization

Charge an organization for usage.

**Parameters:**

- `org_id_to_charge` ( [str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str)) (required): the organization to charge.
- `subtotal` ( [float](https://docs.python.org/3/library/stdtypes.html#numeric-types-int-float-complex)) (required): the subtotal amount in dollars.
- `tax` ( [float](https://docs.python.org/3/library/stdtypes.html#numeric-types-int-float-complex)) (required): the tax amount in dollars to add to the subtotal.
- `description` ( [str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str)) (optional): a short description of the charge to display on the invoice PDF (must be 1000 characters or less).
- `org_id_for_branding` ( [str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str)) (optional): the organization whose branding to use in the invoice PDF and confirmation email.
- `disable_confirmation_email` ( [bool](https://docs.python.org/3/library/stdtypes.html#boolean-type-bool)) (required): whether or not to disable sending an email confirmation for the invoice.

**Returns:**

- ( [viam.proto.app.billing.ChargeOrganizationResponse](https://python.viam.dev/autoapi/viam/proto/app/billing/index.html#viam.proto.app.billing.ChargeOrganizationResponse)): : the invoice id.