Was this page helpful?
Your feedback about this content is important. Let us know what you think.
Additional feedback?
1500 characters remaining
Add-in license schema

Office and SharePoint Add-in license XML schema structure

Office and SharePoint Add-ins

The add-in license schema defines the string that specifies validity and usage properties in add-in licenses.

Last modified: August 07, 2015

Applies to: Office 2013 | Office 365 | Office Add-ins | Project 2013 | SharePoint Add-ins | SharePoint Foundation 2013 | SharePoint Server 2013

Note Note

The names "apps for Office" and "apps for SharePoint" are changing to "Office Add-ins" and "SharePoint Add-ins". During the transition, the documentation and the UI of some Office and SharePoint products and Visual Studio tools might still use the terms "apps for Office" and "apps for SharePoint". For details, see New name for apps for Office and SharePoint.

In this article
Elements
Remarks
Code example: Add-in license XML for a SharePoint Add-in
Additional resources

The add-in license schema defines the structure that specifies usage properties in add-in licenses. If your add-in includes license validation checks, use this schema to create test licenses to test the license validation code in your add-in. For more information, see Add license checks to Office and SharePoint Add-ins.

Use the VerifyEntitlementToken method of the Office Store verification web service to determine if an add-in license is valid. The VerifyEntitlementToken method takes a add-in license token as a parameter, and returns an VerifyEntitlementTokenResponse that contains the license token properties, including whether or not the license token is valid.

To support add-in license testing, the Office Store verification web service does not validate the encryption token or any of the attribute values of license tokens where the test attribute is set to true. However, the service does interpret the token, and all the properties of the VerifyEntitlementTokenResponse object returned by the service can be read.

<r>
  <t 
    aid="{2[A-Z] 8-12[0-9]}" 
    pid="{GUID}" | "string" 
    cid="{16[0-H]}" 
    did="{GUID}" 
    ts="Integer" 
    et="Free" |"Trial" | "Paid"
    sl="true | 1" | "false| 0"
    ad="UTC" 
    ed="UTC" 
    sd="UTC" 
    te="UTC" 
    test="true | 1" | "false | 0"
    ss="0" | "1" | "2" | "3" | "4" />
  <d>VNNAnf36IrkyUVZlihQJNdUUZl/YFEfJOeldWBtd3IM=</d>
</r>

r

Required. The root element.

t

Required. Contains attributes that represent various properties of the add-in license.

Attributes

Attribute

Description

aid

Required text. The asset ID assigned to this add-in by the Office Store.

pid

Required text. The GUID that represents the product ID of the add-in.

The product ID of the add-in is specified in the add-in manifest.

cid

Required text. Represents the purchaser ID. This is an encrypted value of the Microsoft account used by the purchaser of the add-in.

did

For content and task pane Office Add-ins:

This attribute does not apply to content and task pane Office Add-ins.

For mail Office Add-ins:

String that represents the deployment ID of the Exchange deployment to which this add-in license applies. This value should be set to the primary authoritative domain for the Exchange deployment.

For SharePoint Add-ins:

GUID that represents the deployment ID of the SharePoint deployment to which this add-in license applies.

For test licenses for SharePoint Add-ins, you don't need to specify the deployment ID in the add-in license XML. The ImportAppLicense method supplies the correct deployment ID to the license token XML.

ts

Integer representing the total number of users licensed to access this add-in, by this purchaser.

For add-ins that are site licensed, this value is 0.

This attribute does not apply to Office Add-ins.

et

Required text. Enumeration that represents the type of add-in license.

Valid values include Free, Paid, and Trial.

ad

Required text. UTC time-date stamp that represents the acquisition date for the add-in license.

sl

Boolean value that represents whether the add-in license is a site license.

For content and task pane Office Add-ins:

This attribute does not apply to content and task pane Office Add-ins.

For mail Office Add-ins:

This attribute is optional for add-in licenses that are not site licenses. This attribute is required to be equal to true if the mail add-in is site licensed.

For SharePoint Add-ins:

This attribute is optional for add-in licenses that are not site licenses.

ed

Optional text. UTC time-date stamp that represents the expiration date for the add-in license.

This value can be used to check if the trial license is expired.

sd

Required text. UTC time-date stamp that represents one of the following:

  • The initial purchase of the license.

  • The latest manual license recovery time, if the purchaser has performed such a recovery using their Microsoft account.

te

Required text. UTC time-date stamp that represents the date the current add-in license token expires.

test

Optional Boolean value. Represents whether the add-in license is a test license.

ss

Optional integer. Represents the subscription status of the add-in license. This attribute is optional for add-ins that are not being sold as subscriptions.

This attribute accepts integers from 0 through 4. Valid values include:

Integer

Description

0

NotApplicable

The add-in license is not for a subscription add-in.

1

Active

The add-in license subscription is currently paid for.

Recommended user experience:

Full add-in experience.

2

FailedPayment

The automatic monthly billing for the add-in license subscription has failed.

There are several reasons payment may have failed. For example, the credit card being billed might have expired. When payment fails, emails are sent to the Microsoft account paying for the add-in license. However, the user might not check their Microsoft account email on a frequent basis, or, in the case of SharePoint Add-ins, the person paying for the add-in license may not actually be the person using the add-in license.

Recommended user experience:

Present UI in your add-in alerting the user of the problem with billing, so that they can resolve it.

3

Canceled

The add-in license subscription has been canceled, and final monthly billing period the user has paid for has expired.

Recommended user experience:

Present the user with information that their subscription has been cancelled. Provide information about your add-in, along with a hyperlink to your app’s Office Store listing page, so they are encouraged to renew their subscription.

4

DelayedCancel

The add-in license subscription has been canceled, but the subscription is still within the current, monthly billing period the user has paid for. Once the current, paid monthly billing period expires, the subscription status changes to Canceled.

Recommended user experience:

Full add-in experience. Additionally, you may want to present contextual UI to ask the user for feedback on why they are canceling their subscription, or to enourage them to re-subscribe.

d

Required. Encryption token used by the Office Store verification service to determine whether the add-in license token is valid. This is an encrypted signature derived from the literal string contained in the <t> element.

When you submit a test add-in license token to the Office Store verification web service, the service does not perform that validation check of comparing the encrypted signature in the <d> element to the string contained in the <t> element.

Important note Important

When your add-in receives an add-in license token from its hosting environment, be it an Office application or SharePoint, developers are advised not to parse or otherwise manipulate the add-in license token string before passing it to the Office Store verification web service for verification. While the add-in license token is structured as an XML fragment, for purposes of validation the Office Store verification web service treats the token as a literal string. The Office Store verification web service compares the contents of the <t> element to the value of the <d> element, which is an encrypted signature derived from the literal string contained in the <t> element. Any reformatting of the license token, such as adding white space, tabs, line breaks, etc., will change the literal value of the <t> element and therefore cause the license verification check to fail.

When you submit a test add-in license token to the Office Store verification web service, the service does not perform that validation check of comparing the encrypted signature in the <d> element to the string contained in the <t> element. This enables developers to create their own test add-in license tokens for testing purposes without worrying about formatting, or generating the encryption signature for the <d> element.

The following example is the add-in license XML for a SharePoint Add-in, representing a trial add-in for which the purchaser has acquired 30 seats.

<r>
  <t 
    aid="WA900006056" 
    pid="{4FB601F2-5469-4542-B9FC-B96345DC8B39}" 
    cid="32F3E7FC559F4F49" 
    did="{0672BAE9-B41B-48FE-87F1-7F4D3DD3F3B1}" 
    ts="30" 
    et="Trial" 
    ad="2012-01-12T21:58:13Z" 
    ed="2012-06-30T21:58:13Z" 
    sd="2012-01-12T00:00:00Z" 
    te="2012-06-30T02:49:34Z" />
  <d>VNNAnf36IrkyUVZlihQJNdUUZl/YFEfJOeldWBtd3IM=</d>
</r>

Show:
© 2015 Microsoft