Licensing and payment requirements for the Microsoft Teams API

This article describes the licensing and payment requirements for the Microsoft Teams API 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 licensing models are available:

  • model=A is restricted to applications performing a security or compliance function, and requires a supported license. In the future, apps will also be required to pay for the messages they consume beyond the seeded capacity.

  • model=B is restricted to applications that do not perform a security or compliance function. Starting July 5, 2022, model=B billing events reach general availability. There are no licensing requirements for model=B.

  • Evaluation mode (default) enables access to APIs with limited usage per requesting application for evaluation purposes. Change notifications are not sent if the limit is exceeded.

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. Minimum charge of 1 message per API request. 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 Minimum charge of 1 message per API request. 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.

Note

Starting July 5, 2022, model=B billing events for these APIs reach general availability.

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
Get messages across all chats for user N/A None $0.00075 per message Minimum charge of 1 message per API request.
Get messages across all channels N/A None $0.00075 per message Minimum charge of 1 message per API request.

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
Get messages across all chats for user N/A 500 messages per month per app N/A Minimum charge of 1 message per API request.
Get messages across all channels N/A 500 messages per month per app N/A Minimum charge of 1 message per API request.
Updating a chatMessage's policyViolation N/A 500 messages per month per app N/A

In evaluation mode, seeded capacity is shared across all APIs. When seeded capacity is exceeded, API calls with licensing and payment requirements will fail with a 402 error code, and subscriptions with licensing and payment requirements will not send change notifications.

Error type Status code Error message
E5 license requirement not met 402 (Payment Required) User '{userId}' needs a valid license to access this API., Tenant {tenantId} needs a valid license to access this API.
Model B is not supported for Patch API 402 (Payment Required) Query parameter 'model' does not support value 'B' for this API. Use billing model 'A'.
Evaluation capacity exceeded 402 (Payment Required) 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. Not all license violations can be detected, and grace periods might be granted in some cases.

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.

Improper licensing and evaluation mode seeded capacity exceeded

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.

Note

A successful API call does not mean that the proper licensing is in place. Not all license violations can be detected, and grace periods might be granted in some cases. Similarly, API success in evaluation mode does not guarantee the call is within seeded capacity because grace periods might be granted in some cases.

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.

The seeded capacity differs by API; see model=A requirements and model=B requirements.

Price for additional use

In the future, Microsoft will charge a fee for usage over the seeded capacity. You will also be able to associate an Azure subscription to your application registration. The organization that owns the app registration is responsible for the payment, which for multi-tenant apps may be different from the organization that runs the app.

See also