Product Ingestion API for Office Add-ins - public preview

Note

Now available for public preview!

This article covers product-specific guidance for Office Add-ins. For shared concepts like authentication, core API methods, resource-tree queries, configuration requests, and lifecycle management, see the Product Ingestion API documentation.

Tip

You can now create and manage Office Add-in offers with AI agents by using the Marketplace Ingestion MCP server, which connects tools like GitHub Copilot and Visual Studio Code to the Product Ingestion API.

Note

Your Microsoft Entra app registration must be in the seller-associated tenant (the tenant linked to your Partner Center seller account). App tokens from a corporate or Microsoft-homed Entra tenant won't work.

Retrieve existing resource configurations

To retrieve the current configuration for an Office Add-in product, use the resource-tree endpoint with the product's durable ID:

GET https://graph.microsoft.com/rp/product-ingestion/resource-tree/product/12345678-abcd-efgh-1234-12345678901?$version=2026-04-01-preview1

Sample response:

{
  "$schema": "https://schema.mp.microsoft.com/schema/resource-tree/2022-03-01-preview2",
  "root": "product/12345678-abcd-efgh-1234-12345678901",
  "target": {
    "targetType": "preview"
  },
  "resources": [
    {
      "$schema": "https://schema.mp.microsoft.com/schema/product/2026-04-01-preview1",
      "id": "product/12345678-abcd-efgh-1234-12345678901",
      "identity": {
        "externalId": "my-office-addin"
      },
      "type": "officeAddin",
      "alias": "My Office Add-in"
    },
    {
      "$schema": "https://schema.mp.microsoft.com/schema/property/2026-04-01-preview1",
      "id": "property/12345678-abcd-efgh-1234-12345678902",
      "product": "product/12345678-abcd-efgh-1234-12345678901",
      "kind": "officeAddin",
      "categories": ["productivity"],
      "termsConditions": "standardMicrosoft",
      "privacyPolicyUrl": "https://contoso.com/privacy",
      "supportDocumentUrl": "https://contoso.com/support",
      "termsOfUseUrl": "https://contoso.com/terms"
    },
    {
      "$schema": "https://schema.mp.microsoft.com/schema/listing/2026-04-01-preview1",
      "id": "listing/12345678-abcd-efgh-1234-12345678903",
      "product": "product/12345678-abcd-efgh-1234-12345678901",
      "kind": "officeAddin",
      "languageId": "en",
      "title": "My Office Add-in",
      "description": "A powerful add-in for Office applications.",
      "searchResultSummary": "Enhance your Office experience"
    }
  ]
}

Create a new Office Add-in product

To create a new Office Add-in, submit a configure request with the product resource. Set type to officeAddin.

POST https://graph.microsoft.com/rp/product-ingestion/configure?$version=2026-04-01-preview1

Request body:

{
  "$schema": "https://schema.mp.microsoft.com/schema/configure/2022-03-01-preview2",
  "resources": [
    {
      "$schema": "https://schema.mp.microsoft.com/schema/product/2026-04-01-preview1",
      "resourceName": "myNewProduct",
      "identity": {
        "externalId": "my-new-office-addin"
      },
      "type": "officeAddin",
      "alias": "My New Office Add-in"
    }
  ]
}

Sample response:

{
  "$schema": "https://schema.mp.microsoft.com/schema/configure-status/2022-03-01-preview2",
  "jobId": "87654321-dcba-hgfe-4321-109876543210",
  "jobStatus": "running",
  "jobResult": "pending",
  "jobStart": "2026-04-01T10:00:00.0000000Z",
  "resourceStatuses": [
    {
      "resourceName": "myNewProduct",
      "status": "running"
    }
  ]
}

Configure properties

The property resource defines categories, terms and conditions, and policy links for your Office Add-in. Set kind to officeAddin.

POST https://graph.microsoft.com/rp/product-ingestion/configure?$version=2026-04-01-preview1

Request body:

{
  "$schema": "https://schema.mp.microsoft.com/schema/configure/2022-03-01-preview2",
  "resources": [
    {
      "$schema": "https://schema.mp.microsoft.com/schema/property/2026-04-01-preview1",
      "id": "property/12345678-abcd-efgh-1234-12345678902",
      "product": "product/12345678-abcd-efgh-1234-12345678901",
      "kind": "officeAddin",
      "categories": ["productivity", "collaboration"],
      "industries": ["financial-services", "healthcare"],
      "cloudIndustries": ["government"],
      "termsConditions": "standardMicrosoft",
      "termsOfUseUrl": "https://contoso.com/terms",
      "privacyPolicyUrl": "https://contoso.com/privacy",
      "supportDocumentUrl": "https://contoso.com/support"
    }
  ]
}

Property fields

Field Required Description
kind Yes Must be officeAddin
product Yes Reference to the product resource
categories Yes Array of category identifiers
termsConditions Yes Either custom or standardMicrosoft
termsOfUseUrl Yes URL to your terms of use
privacyPolicyUrl Yes URL to your privacy policy
supportDocumentUrl Yes URL to your support documentation
industries No Array of industry identifiers
cloudIndustries No Array of cloud-specific industry identifiers

Configure listing

The listing resource contains storefront information like title, description, and search keywords. Set kind to officeAddin.

Warning

Use Office-supported base locale codes for languageId (for example, en, fr, ja). Region-qualified codes like en-US might cause downstream export failures even if the configure call succeeds.

Note

Ensure your product name is reserved before publishing. The configure endpoint accepts a listing even if the name isn't reserved, but submission fails if the name isn't reserved at submission time.

Office Add-ins support multi-language listings. When configuring multiple listing languages, validate each language listing individually after the configure call completes.

POST https://graph.microsoft.com/rp/product-ingestion/configure?$version=2026-04-01-preview1

Request body:

{
  "$schema": "https://schema.mp.microsoft.com/schema/configure/2022-03-01-preview2",
  "resources": [
    {
      "$schema": "https://schema.mp.microsoft.com/schema/listing/2026-04-01-preview1",
      "id": "listing/12345678-abcd-efgh-1234-12345678903",
      "product": "product/12345678-abcd-efgh-1234-12345678901",
      "kind": "officeAddin",
      "languageId": "en",
      "title": "My Office Add-in",
      "searchResultSummary": "Enhance your Office productivity with powerful features",
      "description": "This add-in helps you work more efficiently in Word, Excel, and PowerPoint. Features include automated formatting, data analysis tools, and seamless integration with your existing workflows.",
      "searchKeywords": ["productivity", "automation", "office"],
      "videoLink": "https://www.youtube.com/watch?v=example"
    }
  ]
}

Listing fields

Field Required Description
kind Yes Must be officeAddin
product Yes Reference to the product resource
languageId Yes Language code using Office-supported base codes (for example, en, fr, ja, pt-BR)
title No Display title (max 200 characters)
searchResultSummary No Short summary for search results
description No Full product description
searchKeywords No Array of keywords for search discovery
videoLink No URL to a promotional video

Configure listing assets

Listing assets include logos and screenshots for your storefront presence.

POST https://graph.microsoft.com/rp/product-ingestion/configure?$version=2026-04-01-preview1

Request body:

{
  "$schema": "https://schema.mp.microsoft.com/schema/configure/2022-03-01-preview2",
  "resources": [
    {
      "$schema": "https://schema.mp.microsoft.com/schema/listing-asset/2026-04-01-preview1",
      "product": "product/12345678-abcd-efgh-1234-12345678901",
      "listing": "listing/12345678-abcd-efgh-1234-12345678903",
      "type": "m365andCopilotLogo",
      "url": "https://yourstorageaccount.blob.core.windows.net/assets/logo.png?sv=...",
      "fileName": "logo.png",
      "friendlyName": "Product Logo"
    },
    {
      "$schema": "https://schema.mp.microsoft.com/schema/listing-asset/2026-04-01-preview1",
      "product": "product/12345678-abcd-efgh-1234-12345678901",
      "listing": "listing/12345678-abcd-efgh-1234-12345678903",
      "type": "m365andCopilotScreenshot",
      "url": "https://yourstorageaccount.blob.core.windows.net/assets/screenshot1.png?sv=...",
      "fileName": "screenshot1.png",
      "friendlyName": "Main Feature Screenshot",
      "displayOrder": 0
    }
  ]
}

Listing asset types

Type Description
m365andCopilotLogo Product logo for storefront display
m365andCopilotScreenshot Product screenshot

Configure Microsoft 365 setup

The Microsoft 365 setup resource configures Entra ID requirements, target cloud plans, and Apple Store availability.

POST https://graph.microsoft.com/rp/product-ingestion/configure?$version=2026-04-01-preview1

Request body:

{
  "$schema": "https://schema.mp.microsoft.com/schema/configure/2022-03-01-preview2",
  "resources": [
    {
      "$schema": "https://schema.mp.microsoft.com/schema/microsoft365-setup/2026-04-01-preview1",
      "product": "product/12345678-abcd-efgh-1234-12345678901",
      "requiresEntraId": true,
      "targetPlan": "gbl",
      "additionalPurchaseRequired": false,
      "appleStoreAvailability": true
    }
  ]
}

Microsoft 365 setup fields

Field Required Description
product Yes Reference to the product resource
requiresEntraId No Whether Entra ID authentication is required
targetPlan No Target cloud plan: chn (China), gbl (Global), ger (Germany), gov (Government)
additionalPurchaseRequired No Whether additional purchases are required
appleStoreAvailability No Whether the product is available in the Apple Store

Configure technical configuration

The technical configuration for Office Add-ins uses a payload-based model. You upload your XML manifest file to Azure Blob Storage and provide the SAS URI.

POST https://graph.microsoft.com/rp/product-ingestion/configure?$version=2026-04-01-preview1

Request body:

{
  "$schema": "https://schema.mp.microsoft.com/schema/configure/2022-03-01-preview2",
  "resources": [
    {
      "$schema": "https://schema.mp.microsoft.com/schema/office-addin-technical-configuration/2026-04-01-preview1",
      "product": "product/12345678-abcd-efgh-1234-12345678901",
      "payloads": [
        {
          "payload": {
            "sasUri": "https://yourstorageaccount.blob.core.windows.net/uploads/manifest.xml?sv=...",
            "fileName": "manifest.xml"
          }
        }
      ]
    }
  ]
}

Technical configuration payload fields

Field Required Description
sasUri Conditional Azure Blob SAS URI for the XML manifest file. Required for new uploads.
fileName Yes Display name of the uploaded file
payloadId Conditional Server-assigned ID from a previous upload. Use instead of sasUri to reuse an existing payload.

Note

You must provide either sasUri (for new uploads) or payloadId (to reuse an existing payload), but not both.

Reusing an existing payload

After the initial upload is processed, the API returns a payloadId. You can use this ID in subsequent requests to reference the same payload without re-uploading:

{
  "$schema": "https://schema.mp.microsoft.com/schema/configure/2022-03-01-preview2",
  "resources": [
    {
      "$schema": "https://schema.mp.microsoft.com/schema/office-addin-technical-configuration/2026-04-01-preview1",
      "product": "product/12345678-abcd-efgh-1234-12345678901",
      "payloads": [
        {
          "payload": {
            "payloadId": "98765432-abcd-efgh-1234-12345678901",
            "fileName": "manifest.xml"
          }
        }
      ]
    }
  ]
}

Publishing

Publish to live

{
  "$schema": "https://schema.mp.microsoft.com/schema/configure/2022-03-01-preview2",
  "resources": [
    {
      "$schema": "https://schema.mp.microsoft.com/schema/submission/2026-04-01-preview1",
      "id": "submission/12345678-abcd-efgh-1234-12345678904",
      "product": "product/12345678-abcd-efgh-1234-12345678901",
      "target": {
        "targetType": "live"
      }
    }
  ]
}

Important

A successful configure response doesn't guarantee a successful submission. The configure endpoint is more permissive than the submission pipeline. Common causes of submission failure include missing reserved names, unsupported locale codes, and missing implicit resources. Validate your full resource tree before submitting.

Note

Office Add-ins are free-only products. Pricing is managed internally and isn't configurable through the API.

Resource lifecycle states

Resources support lifecycle state management. To deprecate a resource, set lifecycleState to deleted:

{
  "$schema": "https://schema.mp.microsoft.com/schema/configure/2022-03-01-preview2",
  "resources": [
    {
      "$schema": "https://schema.mp.microsoft.com/schema/listing/2026-04-01-preview1",
      "id": "listing/12345678-abcd-efgh-1234-12345678903",
      "product": "product/12345678-abcd-efgh-1234-12345678901",
      "kind": "officeAddin",
      "languageId": "en",
      "lifecycleState": "deleted"
    }
  ]
}

To restore a deprecated resource, set lifecycleState back to generallyAvailable.

For more information about lifecycle management, see the base API documentation.

Resource API reference

Resource type Description Schema URL
product Main resource defining product name and type https://schema.mp.microsoft.com/schema/product/2026-04-01-preview1
property Categories, industries, and legal contracts https://schema.mp.microsoft.com/schema/property/2026-04-01-preview1
listing Product descriptions for storefront https://schema.mp.microsoft.com/schema/listing/2026-04-01-preview1
listing-asset Screenshots and marketing assets https://schema.mp.microsoft.com/schema/listing-asset/2026-04-01-preview1
microsoft365-setup M365-specific setup configuration https://schema.mp.microsoft.com/schema/microsoft365-setup/2026-04-01-preview1
office-addin-technical-configuration Technical configuration with XML manifest https://schema.mp.microsoft.com/schema/office-addin-technical-configuration/2026-04-01-preview1
submission Publishing state and actions https://schema.mp.microsoft.com/schema/submission/2026-04-01-preview1

API versions and updates

Version Description
2026-04-01-preview1 Initial preview release for Office Add-ins support

Related content

  • Last updated on