Version:
Only show these results:

Usage calculation and billing

This page explains how Nylas calculates your usage, the billing states you might encounter for connected accounts, and more.

Nylas bills you on the 5th of the month for the previous calendar month's use. For example, the bill you get on October 5th is for the accounts that were connected between September 1st and September 30th. Your bill might include your base plan (which can include a specific number of connected accounts), as well as any overages.

ℹ️ The Nylas billing month is calculated in the UTC time zone. Take this into account if you plan to do periodic cleanup of connected accounts. This also means you might receive your bill a little early if you are in a time zone west of UTC.

How Nylas calculates usage

🔍 In Nylas v3, "grants" replace "Connected Accounts". For billing purposes, however, they're referred to as "connected accounts" ("CAs"). To learn more about terminology changes in v3, see the v3 features and changes documentation.

Nylas calculates your usage by multiplying the number of connected accounts by the effective price per account for your organization's billing plan. If the number of connected accounts per month is less than or equal to the number of accounts included in your billing plan, Nylas bills you the regular monthly ("base") rate for the plan. If your organization exceeds the number of connected accounts included in your billing plan, Nylas bills you the regular monthly rate plus a prorated amount for each extra account.

Calculating usage for v3

If your organization is using both the v2 and v3 APIs, Nylas calculates your usage based on a de-duplicated list of connected accounts.

If your organization migrated from Nylas v2 to v3, the number of connected accounts for both versions will be combined on your invoice. Your organization is billed for v3 when it has at least one live v3 Nylas application with at least one active grant associated to it.

How Nylas identifies accounts

Each connected account is uniquely defined by both its associated email address and the server settings it uses to authenticate. This means that accounts are counted more than once if the same email address authenticates with different server settings. For example, if leyah@example.com authenticates on December 2nd with the mx.mail.com server setting, then re-authenticates on December 12th with the mailbox.mail.com server setting, the user is counted twice for December.

Accounts that are connected to multiple Nylas applications within your organization count as separate accounts.

Nylas v3 does not have explicit sync states, so an account's billing status changes only when a grant is created or deleted. Grants continue to be billable as long as they exist, including if they are in the invalid state.

Account re-authentication in v3

Re-authenticating a grant does not create a new grant_id, because Nylas associates grants with email addresses. When Nylas receives an authentication request, it checks to see if a grant is already associated with the end user's email address. If one exists, Nylas re-authenticates the grant instead of making a new one. See the Manage grants documentation for more information.

🔍 If the end user tries to re-authenticate using the same email address, but a different provider, Nylas creates a grant instead of re-authenticating the existing one.

Account re-authentication in v2

If re-authenticating an account generates a new account_id, you can cancel the previous account and use only the new one to make sure Nylas doesn't bill you twice. You can also ask your end users to re-authenticate using the same server settings to avoid this issue. For more information, see the account re-authentication documentation.

Account billing states in v2

Nylas charges you for the accounts connected to your organization's v2 Nylas applications, so it's helpful to understand Nylas' account billing states.

💡 Tip: You can check an account's billing_state by making a GET /a/<NYLAS_CLIENT_ID>/accounts request, or a GET /a/<NYLAS_CLIENT_ID>/accounts/<ACCOUNT_ID> request.

A connected account is one whose billing_state is changed to paid for any period of time within a given month. Nylas doesn't prorate account usage within a month. If an account was connected at any time in a given month, Nylas counts it as connected for the entire month, regardless of the account's sync_state. For example, during September, if you have 50 accounts in a paid state and then authenticate a new account, you will be charged for 51 accounts for September on October 5th.

The following table describes when Nylas charges for an account.

Billing State Sync State Does Nylas charge?
paid invalid ☑️
paid running ☑️
paid stopped ☑️
paid partial ☑️
paid exception ☑️
cancelled invalid ⬜
cancelled running ⬜
cancelled stopped ⬜
cancelled partial ⬜
cancelled exception ⬜
deleted invalid ⬜
deleted running ⬜
deleted stopped ⬜
deleted partial ⬜
deleted exception ⬜

An account's billing_state is set to paid the first time you authenticate it to the Nylas API. If you downgrade or cancel it (the billing_state is changed to cancelled) or delete the account (the billing_state is changed to deleted), Nylas blocks any API requests made by that account.

You can upgrade a cancelled account to reactivate it. This changes its billing_state to paid and allows the account to make requests to the Nylas APIs.

Nylas data centers

Nylas offers multiple data centers to help you comply with legal requirements.

⚠️ If you authenticate the same account in multiple data centers, Nylas charges you for each occurrence of the connected account.

View paid invoices

Nylas stores your paid invoices. If you're an Administrator for your organization, you can view and download them in the Nylas Dashboard.

View paid invoices for v3

Follow these steps to view and download your organization's paid invoices in the v3 Nylas Dashboard:

  1. Log in to the v3 Nylas Dashboard.
  2. Click the Account menu at the upper-right of the page, and select Billing.

The Billing page shows your organization's plan settings, invoice information, and payment method.

View paid invoices for v2

Follow these steps to view and download your organization's paid invoices in the v2 Nylas Dashboard:

  1. Log in to the v2 Nylas Dashboard.
  2. Click Org Settings in the left navigation menu, then select the Billing tab.
  3. Choose the invoice that you want to view or download.