Licensing and payment requirements for the Microsoft Teams API

This article describes the licensing and payment requirements for the Microsoft Teams APIs in Microsoft Graph.

Some APIs provide the option to choose a licensing and payment model via the model query parameter; others only support one model or do not support a licensing and payment model. The following APIs have consumption charges:

The following licensing models are available:

Note

Active pricing events for these APIs started on July 5th, 2022. We require applications to complete this form to provide an active Azure subscription for billing purposes. For more details, see Payment and billing updates.

model=A requirements

model=A is restricted to applications performing a security or compliance function. For details, see the API Terms for Security & Compliance Applications section of the product terms for Microsoft Azure Services.

API Who needs a license Seeded capacity Price for additional use Notes
chatMessage change notifications Message sender 800 messages per user per month per app $0.00075 per message Seeded capacity is shared with conversationMember change notifications
conversationMember change notifications Any user in the tenant 800 notifications per user per month per app $0.00075 per notification Seeded capacity is shared with chatMessage change notifications
Get messages across all chats for user Named user 1600 messages per user per month per app $0.00075 per message The named user is the user identified in the GET request URL. Requests returning an empty list, will be charged 1 message. Seeded capacity is shared with channel export.
Get messages across all channels Any team member 1600 messages per user per month per app $0.00075 per message Requests returning an empty list will be charged 1 message. Seeded capacity is shared with chat export.
Updating a chatMessage's policyViolation Message sender 800 messages per user per month per app $0.00075 per message

model=B requirements

model=B is restricted to applications that do not perform a security or compliance function. For details, see the API Terms for Security & Compliance Applications section of the product terms for Microsoft Azure Services.

API Who needs a license Seeded capacity Price for additional use Notes
chatMessage change notifications N/A None $0.00075 per message
conversationMember change notifications N/A None $0.00075 per notification
chat change notifications N/A None $0.00075 per message
Get messages across all chats for user N/A None $0.00075 per message Requests returning an empty list, will be charged 1 message.
Get messages across all channels N/A None $0.00075 per message Requests returning an empty list, will be charged 1 message.

Evaluation mode (default) requirements

API Who needs a license Seeded capacity Price for additional use Notes
chatMessage change notifications N/A 500 messages per month per app N/A
conversationMember change notifications N/A 500 messages per month per app N/A
chat change notifications N/A 500 messages per month per app N/A
Get messages across all chats for user N/A 500 messages per month per app N/A Requests returning an empty list, will be charged 1 message.
Get messages across all channels N/A 500 messages per month per app N/A Requests returning an empty list, will be charged 1 message.
Updating a chatMessage's policyViolation N/A 500 messages per month per app N/A

Required licenses for model=A

The user will need a license that supports the Microsoft Communications DLP service plan, such as one of these supported licenses. Which user needs the license varies by API; for details, see model=A requirements.

Guest users are exempt from these licensing requirements. Similarly, messages sent from outside the tenant (federated chat) are exempt. Consumption meters still apply.

It is the responsibility of the tenant owner (not the app owner) to ensure users are properly licensed. Admins can use the Information protection license report in Teams admin center to see which users don't have a supported license.

Many supported licenses offer free trials. Office 365 E5 for instance has a Free trial link underneath the Buy button.

You can get a free Microsoft 365 E5 developer sandbox subscription with 25 user licenses through the Microsoft 365 Developer Program.

Note

The Microsoft Communications DLP service plan must be enabled before it can be licensed. Licenses can be managed in the Azure portal or the Microsoft 365 admin center. You can also assign licenses to a group account by using PowerShell and Microsoft Graph.

Licenses, payment and seeded capacity

Seeded capacity is the amount of capacity that an app can use before a consumption meter is charged. Capacity is pooled at the tenant level—the seeded capacity for all users in the tenant is added up and compared against the app's usage in the tenant. Seeded capacity is per app per tenant—apps won't run out of seeded capacity if another app runs out.

Billing model Sample functions Seeded Capacity License required Azure subscription required
model=A Security and Compliance. See model=A details Yes (Microsoft 365 E5 eligible license) Yes
model=B Backup and Restore, migration, sentiment analysis, analytics and insights, etc. None No Yes
evaluation model Backup and Restore, migration, sentiment analysis, analytics and insights, etc. 500 messages per month per app No No

In the event that improper licensing is detected, the API call will fail and data will not be returned. Specifically, for most APIs, attempting to GET messages for an unlicensed user will result in a 402 error code. For change notifications, messages sent by unlicensed users will not generate a change notification. Similarly, API calls and change notifications used in evaluation mode in excess of the seeded capacity will fail.

Error code Scenario Sample error message
402 (Payment Required) Passing model=A without a Microsoft E5 license ...needs a valid license to access this API..., ...tenant needs a valid license to access this API...
402 (Payment Required) Calling Patch API passing model=B ...query parameter 'model' does not support value 'B' for this API. Use billing model 'A'...
402 (Payment Required) Evaluation mode capacity exceeded ...evaluation mode capacity has been exceeded. Use a valid billing model...

Note

A successful API call does not mean that the proper licensing is in place. Similarly, API success in evaluation model does not guarantee the call is within seeded capacity.

Payment and billing updates

In October 2021 we communicated upcoming charges for the consumption of these APIs; on July 5, 2022, these prices take effect as previously announced.

If your applications are or will be calling any of these APIs, we require you to complete this request form providing an active Azure subscription. When the request form has been submitted to register an application, you can continue using these APIs. We will follow up with next steps to onboard your application to billing.

Please note that the organization that owns the app registration is responsible for the payment and the Azure subscription should also be active in the same tenant. For multitenant apps, the organization that registered the app might be different than the organization that runs the app.

Monitor costs billed for the metered Microsoft Teams APIs

This section describes how to monitor costs billed for the metered Microsoft Teams APIs.

A subscription owner, or anyone with appropriate RBAC (Roles Based Access Control) permissions, can use Cost Analysis to track metered API consumption, as follows:

  1. Sign in to the Azure portal at https://portal.azure.com.
  2. Go to Cost Management + Billing > Cost Management > Cost analysis.
  3. For the filter near the top, select Service name: Microsoft Graph Servies.
  4. For the Group by dropdown menu near the right, select Meter.

This view offers a convenient way to observe API consumption per day over a period of time.

You can also use the pie charts near the bottom to further break down the costs for analysis. Note that for Microsoft Graph metered APIs, the Resource GUID is the app ID; Resource Groups or Resource Tags are not supported.

Screenshot of the Cost Management and Billing page in the Azure portal

For more details about cost management, see Cost Management + Billing documentation.

Frequently asked questions

Scenario Details
Did billing actually started on July 5th? Yes, we are onboarding partners in phases. For continued access, please fill this request form and provide an active Azure subscription.
What should I expect after providing an Azure subscription? You can continue calling these metered APIs; we will contact the email provided in the request form to onboard the registered application to billing.
Do I need to provide an Azure subscription if my application is not calling metered APIs? Is recommended as most scenarios use metered APIs, see also: protected APIs.
What happens if no Azure subscription is provided? • No payment-related errors if the application is not calling metered APIs.
• If no model is being passed, the evaluation model value will be used by default.
• If calling a metered API passing model=A, a Microsoft 365 E5 eligible license and Azure subscription should be provided.
• If passing model=B when calling metered APIs, an active Azure subscription should be provided.
How do I create an Azure subscription? The Azure subscription must be available in the same tenant where the app is registered. Customers with MCA or EA agreements can get a subscription from their existing account. Is also possible to create a PAYG subscription using a credit card or pay by check or wire transfer, for details see cost management and billing.
Who is responsible for the payment in the case of multitenant apps? The organization that owns the app registration.
Is possible to differentiate billing from multitenant or single tenant app? Yes, this information must be provided as part of Azure billing details.
Is there a charge when no message is returned using any model? To discourage frequent polling, API requests that return an empty list of messages will be charged one message. In the case of evaluation model, the call will count towards the 500 messages per month per app allowed.
Where can I monitor the cost and billing? A subscription owner, or anyone with appropriate RBAC (Roles Based Access Control) can use Azure Cost Analysis tool to track consumption per day or filter by meter, service name, resource ID among other parameters. For more details refer to our documentation.
Is there a volume discount? Flat rates apply.
Are these APIs enrolled in Microsoft Azure Consumption Commitment (MACC) program? Not at this moment.
Is it possible to obtain an extension, in case an organization didn't plan for this? We can grant a short term extension on case by case basis. Fill out this request extension form providing your Azure subscription and reach out to TeamsAPIBilling@microsoft.com.