Migrate to MAU pricing

This guide is for accounts on resource-based pricing that want to move to MAU pricing. Under MAU pricing you pay for the number of unique users that interact with your application each month upfront, rather than for messages, channel minutes and connection minutes in arrears.

Migrating is a four-step process:

Upgrade your SDKs to versions that declare whether they run on a user's device or on your servers.
Set a unique clientId for every user, so that Ably can count them.
Estimate your MAUs by running your application for a month on your current resource-based package.
Switch your package in your account dashboard.

Steps 1 and 2 are not optional. Ably counts an MAU as a unique clientId that connects or makes a request from a device SDK. On an MAU account, traffic from an older SDK is rejected, as is a connection from a device that has no clientId set. Any traffic that is not declared as coming from a server or agent is counted as a user. If you switch to MAU pricing before completing these steps your users will be unable to connect.

Devices, servers and agents

MAU pricing counts users, so Ably needs to know which side of your application each connection or request comes from:

A device is anything a user runs: a browser, a mobile or desktop app, or an embedded device. Clients on devices are counted as MAUs, and every one of them must have a clientId.
A server is infrastructure you operate: an application server, a serverless function, a worker or a bot. Clients on servers are never counted as MAUs.
An agent is a process that uses the AI Transport SDK to respond to users. Agents run on your servers and are never counted as MAUs.

The SDK package you install declares the side: the device package on devices, the server package on servers and agents.

What changes

	Resource-based pricing	MAU pricing
What you pay for	A base package fee, plus messages, channel minutes and connection minutes used	A package with an MAU allowance, pre-paid monthly or annually, plus additional MAUs above that allowance
Packages	Free, Standard, Pro, Enterprise	Free, Pro, Business, Enterprise
When you are billed	Monthly in arrears	Allowance in advance, additional MAUs in arrears
Identifying users	Optional	Required. Every user must have a `clientId`
Servers and agents	Not distinguished from users	Must be declared as servers or agents, and are then excluded from the MAU count

Step 1: Upgrade your SDKs

MAU pricing depends on Ably knowing whether each connection or request comes from a user's device or from one of your servers. The current Pub/Sub SDKs declare this for you: each is published as a separate device package and server package, and the package you install declares the side. Earlier SDK versions do not declare a side, and their traffic is rejected once your account is on MAU pricing.

Upgrade the Ably SDKs in your application to the latest major version before you switch:

SDK	Version
Ably Pub/Sub JavaScript	3.0+
Ably Pub/Sub Java	2.0+
Ably Pub/Sub Python	4.0+
Ably Pub/Sub Go	2.0+
Ably Pub/Sub C# .NET	2.0+
Ably Pub/Sub Swift	2.0+
Ably Pub/Sub Objective-C	2.0+
Ably Pub/Sub Ruby	2.0+
Ably Pub/Sub Flutter	2.0+
Ably Pub/Sub PHP	2.0+
Ably Pub/Sub Laravel PHP	2.0+
Ably Chat JavaScript	2.0+
Ably Chat Kotlin	2.0+
Ably Chat Swift	2.0+
Ably AI Transport JavaScript	0.11+
Ably Spaces JavaScript	0.6+
Ably Models JavaScript	0.1+

Things to be aware of whilst upgrading:

On devices, install the device package and create your client with its createClient() function. A device client must be given a clientId. Ably rejects a device connection without one on an MAU account.
On servers, install the server package and create your client with createHttpClient() for request-only use, or createRealtimeClient() where your server needs a realtime connection. Server clients are excluded from the MAU count and from per-clientId limits. On token authentication, the token must also carry the signed x-ably-clientType claim with the value server, or Ably rejects the connection with a 401.
The Chat, Spaces and LiveSync SDKs are not split. Upgrade each to its latest major version and pass it a Pub/Sub client that you created from the device or server package.
The AI Transport SDK is not split either. It creates a transport over the realtime client you pass to createTransport(), so pass a realtime client from the device package in your user-facing application and one from the server package in your agent. The agent is then a server client and is not counted as an MAU.
LiveObjects is a plugin that loads into a realtime client on either side and needs no change beyond the Pub/Sub upgrade.

Traffic that does not use an Ably SDK

If you call the REST API directly, use a custom realtime client, or connect through a protocol adapter, declare your servers as described in how MAUs are counted. Anything that does not declare itself as a server is counted as a user.

Step 2: Set a clientId for every user

An MAU is a unique clientId that is active in a calendar month, so every device client must have a clientId before you switch. Follow the rules in how MAUs are counted: one clientId per user, the same clientId for that user on every device, never shared between users. Devices that connect without a clientId are rejected on an MAU account.

Step 3: Estimate your MAUs (optional)

Once your SDKs are upgraded and every user has a clientId, run your application for a full calendar month on your current resource-based package. Ably counts your MAUs during this period, so that you can see which MAU allowance you'd need to purchase for your account.

To view your MAU count:

Log in to your account.
Select MAU usage from the Reports section of the account sidebar.

The report shows the number of unique users active in the current and previous months, per app. Use the previous full month, adjusted for any growth you expect, to choose your MAU allowance. The pricing page shows the price for each package at each allowance. If your usage is above 50,000 MAUs, contact sales to arrange a custom package.

Step 4: Switch your package

To switch your account to MAU pricing:

Ensure you are the account owner.
Log in to your account and select the Packages page.
Select the MAU package, MAU allowance and billing frequency you require, then follow the instructions to review and pay.

When the switch takes effect depends on your current package:

From a paid resource-based package, your account finishes the current calendar month on resource-based billing, so that the month's usage can be invoiced as normal. Your MAU package, its allowance and its limits take effect on the 1st of the following month. You receive two invoices at that point: the final resource-based invoice for the previous month's usage in arrears, and the first MAU invoice for your allowance in advance.
From a Free package, the switch takes effect immediately and your first month's allowance is charged pro-rata for the remainder of the month.

Once your account is on MAU pricing, the billing page describes how package changes and additional MAUs are invoiced. Set up a billing alert to be notified when your MAUs or your spend on additional MAUs cross a threshold.