Share via

Build AI apps and agents

This section provides guidance on building your solution to meet technical requirements and best practices for Microsoft Marketplace. It covers the core development requirements for integration, recommended best practices for AI solutions, and useful samples and templates provided to accelerate development.

Requirements

Offer type selection

Before writing a line of code, decide on the right Marketplace offer type for your solution. Use Microsoft's guidelines or an "Offer Selection"advisor tool to choose among SaaS, Azure Application, Container, or virtual machine (VM) offer. (We provide more details on offer types in the Publishing Guidance section, but it's crucial to pick correctly upfront.) In summary, choose:

  • A SaaS offer: If you'll host a central web service for multiple customers
  • An Azure Application: Solution Template or Managed Application, if you need to deploy multiple resources into the customer's Azure environment
  • A Container offer: If you're delivering your solution as a container image to run in the customer's tenant
  • or use a Virtual Machine offer for a self-contained VM solution

Selecting the proper category now drives many development requirements (for example, only SaaS offers use the Fulfillment APIs, containers need a deployment package, etc.). Microsoft's internal "Offer Selection App" or guidelines can help validate your choice at this stage. In this document, we focus on the SaaS Offer as it's the most used across software development companies (SDCs).

Flowchart showing a large gray box representing the software publisher's subscription. Inside it, a blue section contains many user icons across the top and infrastructure icons (databases and files). At the bottom, three labeled customer areas Customer A, Customer B, and Customer C, each include database and storage icons, indicating dedicated deployments per customer. On the right side, separate customer application instances are shown as stacked blue rectangles with database icons, each associated with an individual customer icon.

Implement SaaS fulfillment API v2

If you're building a transactable SaaS offer, fully integrate with the SaaS Fulfillment APIs v2. Your application must implement all the required REST endpoints and logic to handle the subscription lifecycle: Resolve, activate, suspend, cancel, and update. In practice:

  • Resolve is called when a customer tries to install/subscribe - your service receives a token and should return an account mapping (fulfillment ID)
  • Activate is called to confirm a subscription (often after the customer lands on your site)
  • Suspend/Resume are called when a subscription is put on hold (for example, payment issue) or reactivated
  • Cancel is called when the customer or Microsoft terminates the subscription
  • Update is called when the customer changes their plan (SKU) or license count

Plan out how your backend responds to each of these required REST endpoints with the necessary business logic (for example, Provision resources on Activate, restrict access on Suspend, etc.). Use the v2 API endpoints with proper authentication and return the expected HTTP statuses. Microsoft provides client libraries and samples for this purpose. Thoroughly test these flows end-to-end (more on testing in the Publishing section) to ensure your integration is solid. This is a mandatory requirement for any SaaS offer.

Landing page and token processing

Develop a landing page for SaaS offers that correctly processes the marketplace SaaS token on redirection. When a user acquires your SaaS offer, the marketplace directs them to your configured landing page URL along with a token (in the URL query). Your application needs to capture that token and use the Fulfillment API (Resolve) to get subscription details, linking that marketplace purchase to an account in your system. Ensure this page provides smooth onboarding: for example, after token verification, you might ask the user to create or link an account if not already, then call Activate to start their subscription.

Tip

Use or adapt the sample landing page provided by Microsoft's SaaS Accelerator or starter kits, which already handle token parsing and subscription status display. A well-implemented landing page prevents many common errors (like customers being stuck after purchase), so invest effort here.

Diagram showing the end-to-end SaaS subscription activation flow across three columns: Customer, Publisher Services, and Microsoft Entra ID. The customer initiates a 'Get it now' purchase, which creates a subscription and sends an email. The customer selects 'Configure account,' sending a purchase ID token to the publisher's landing page. The landing page renders, and the customer submits a signup request. Publisher Services logs the customer in using Microsoft Entra ID single sign-on (SSO) and obtains an access token to call the SaaS API. Microsoft Entra ID issues the access token in JSON Web Tokens (JWT) format. The landing page then calls Microsoft's subscription resolve endpoint with the access token so Microsoft can validate the purchase ID token and return purchase details. Publisher Services signs up the customer, provisions the account, and calls Microsoft's activate endpoint to activate the SaaS subscription. Billing begins after activation.

Tenant linking workflow

Design the tenant linking workflow for customers' environments. If your solution requires access to the customer's Azure tenant or other resources (common in multitenant SaaS or when using Azure APIs on their behalf), you must provide a way for the customer to grant that access. This often means implementing an OAuth consent flow or allowing the customer to input their Azure Tenant ID and admin consent. For instance, your landing page or application might display a button "Connect to Microsoft," which triggers Azure AD OAuth, requesting permissions (like reading specific data or deploying resources) if needed. When the customer grants consent, store their tenant or auth token securely mapped to their subscription. This step is essential for any solution that integrates with the customer's Azure environment post-purchase. Make it as simple as possible (document what permissions you need and why). If your solution doesn't need anything from the customer's side beyond the basic subscription (for example, a pure SaaS app that just hosts data), then this might not apply, but double-check with the SDC or architect if any linking is required.

Implement metering (if usage-based)

For any usage-based billing components, set up metering integration to report consumption. The Marketplace allows usage-based charges in addition to (or instead of) flat fees, but you as the publisher must emit the usage events via the Marketplace Metering API. Identify what usage you charge for (for example, number of documents processed, API calls made, etc.). In your solution:

  • Instrument the code to count these usage events per customer subscription
  • At appropriate intervals (usually hourly or daily), call the Metering API with each subscription's usage for each dimension
  • Ensure idempotency or unique IDs for metering events to avoid double billing

For example, if you bill per 1,000 messages processed, your service might accumulate counts for each customer and every hour send the totals to Microsoft for billing. Use the provided Metering client samples to see how to format and authenticate these calls. Testing is key: verify that usage appears correctly in Partner Center reports. Without metering, usage-based plans don't charge customers correctly, so metering integration is a critical piece for revenue.

Plan and SKU design

Define a plan/SKU structure that aligns with customer value and your billing strategy. Each offer can have one or more plans (SKUs) - for instance "free trial," "standard," "enterprise." Design these plan/SKU structures carefully:

  • Make sure the differentiation is clear (features, limits, support level)
  • Price them in a way that matches how customers derive value (for example, per user, per capacity, consumption bundle, etc.)
  • Align with how customers budget: maybe a lower-cost plan for SMB and a higher for enterprise, or monthly vs annual billing options

Ensure that any usage meters tie logically into these plans (for example, the "standard" plan might include up to 1000 queries/month and then charge per query beyond that). Also consider private plans for special agreements (Marketplace allows hidden SKUs that only specific customers can see, often used for custom deals). Early in development, validate with your business team that the app can enforce these plan differences (like if Plan A has feature X disabled, your code should reflect that enforcement). A well-thought-out SKU strategy not only appeals to customers but also simplifies development (since you know exactly what to build for each tier).

Production-ready architecture

Build a production-ready, multitenant architecture with strong isolation between customer data. This ties into security isolation, but from a development perspective: you should implement your solution as if it's going to serve many customers reliably and securely. This includes:

  • Using scalable Azure services (for example, Azure App Service with autoscaling, Azure SQL or Cosmos DB with partitioning by tenant, etc.)
  • Implementing strict checks so that any request is always executed in the context of a specific customer and can't bleed into another's context
  • Testing with multiple concurrent tenants to see that performance holds up (one tenant running a heavy job shouldn't starve others)
  • Incorporating feature flags or config per tenant if needed (some customers might have slightly different settings)

Essentially, avoid any design that assumes one-customer or that is hardcoded for a single instance. Even if you start with one pilot customer, design for many. Use Azure's inherent isolation features (separate storage containers per tenant, row-level security in databases, etc.). This pays off as you onboard more customers and ensure no one's data or experience is impacted by others. It's also something marketplace certification and enterprise clients will evaluate (they might ask, "how do you isolate customer data?" - you'll be ready with a solid answer and architecture diagram).

Diagram titled 'multitenant Solution - Everything is Shared.' A single software publisher subscription is shown as a large gray box containing a blue shared environment. At the top are many user icons representing multiple customers accessing the same shared system. Below them are shared solution assets, illustrated with a database icon and file icons, indicating all customers use the same underlying infrastructure and resources.

Environment strategy (dev > stage > production)

Set up separate development, staging, and production environments with their own credentials and endpoints. This is standard practice but absolutely vital for a marketplace solution, since you'll go through multiple rounds of testing and updates:

  • Dev: For your internal development and testing. Use this environment for daily builds, possibly with mocked integration endpoints
  • Stage (test): A stage that closely mirrors production configuration, used for certification testing and dry-runs. This environment should have the same integrations (for example, talking to the actual Marketplace APIs in sandbox mode, etc.), but isolated from Production data
  • Production: The live environment for customers

Use separate Azure resources or subscriptions for each to avoid cross-contamination. Manage separate sets of API keys and connection strings. For example, store separate sets of API keys and connection strings in separate Key Vaults. The idea is that you can confidently test new releases in Stage (maybe even by using a Partner Center "Preview" draft of your offer pointing to Stage URLs) without affecting real customers. Once everything checks out in Stage, you promote the changes to Production. This strategy also means if something goes wrong in Production, you have a stable Stage to compare against (or even failover to), depending on your setup. Document the differences (for example, "Stage uses test payment and a fake email service, Production uses real credit card charging and our live email system"). Microsoft's review team might perform certification on a non-Production environment if you set that up, which is safer for you.

Next step

  • Last updated on