Microsoft Advertising Shopping Content API: Setup & Fix Guide
Why This Is Happening
You've set up your Microsoft Advertising Shopping Content API integration, your code looks right, your credentials are in place , and still nothing works. Requests bounce back with 401 errors, your product catalog never updates, or your Microsoft Merchant Center store shows data that's hours out of date. I've seen this exact scenario on dozens of merchant integrations, and the problem almost always comes down to one of three things: authentication scope misconfiguration, a missing developer token header, or a Merchant Center store that simply wasn't configured for API access before the first call was made.
The Microsoft Advertising Shopping Content API is a RESTful interface that lets you manage your Microsoft Merchant Center (MMC) product catalogs programmatically. That means you can insert, update, and delete product offers without touching the MMC web interface or scheduling FTP/SFTP uploads. In theory, that's a huge win for any merchant running a live catalog with real-time pricing. In practice, the setup has more moving parts than the documentation suggests , and the error messages you get when something's wrong are rarely helpful.
Here's what makes this API uniquely tricky compared to other Microsoft Advertising integrations: it sits at the intersection of three separate systems, your Microsoft account, your Microsoft Advertising account, and Microsoft Merchant Center. All three have to be aligned before a single API call succeeds. Miss one step in any of those systems and you'll get generic auth errors that point you in the wrong direction.
Since June 1, 2022, Microsoft also requires multi-factor authentication for all users signing in through third-party applications that touch the Bing Ads API, Content API, or Hotel APIs. If your integration was built before that date and you haven't updated it to use the msads.manage OAuth scope, that's almost certainly why your authentication is failing today. This catches a lot of developers off guard, the app worked fine for years, then suddenly stopped after a routine token refresh.
There's also a subtle catalog configuration issue that trips up even experienced developers. When Microsoft Merchant Center creates your store, it generates a default catalog automatically. But if you want to target a specific catalog with your API calls, rather than the default, you need to pass the bmc-catalog-id query parameter explicitly. Without it, every product operation you make silently hits the default catalog, which may not be what you intended at all.
I know this is frustrating, especially when a broken feed directly impacts your Shopping campaign performance and ad spend. Let's fix it systematically. Browse all Microsoft fix guides →
The Quick Fix, Try This First
Before going through the full setup checklist, run this sanity check. It resolves the majority of Microsoft Advertising Shopping Content API failures in under five minutes.
Open your API request headers and confirm you have both of these set correctly:
DeveloperToken: YOUR_DEVELOPER_TOKEN_HERE
AuthenticationToken: YOUR_OAUTH_ACCESS_TOKEN_HEREBoth headers are required on every single request. The DeveloperToken is the static token you got from the Microsoft Advertising Developer Portal. The AuthenticationToken is your OAuth access token, which expires and needs to be refreshed periodically. Nine times out of ten when someone tells me their API "just stopped working," it's an expired AuthenticationToken that was never being refreshed properly in their integration code.
If you're managing catalogs on behalf of another advertiser, not your own account, you also need two additional headers:
CustomerId: CUSTOMER_ID_OF_THE_ACCOUNT_YOU_MANAGE
CustomerAccountId: ANY_ACCOUNT_ID_FROM_THAT_CUSTOMERSkipping those on a managed-account scenario causes the API to silently fall through to your own account, which then returns a 403 because the catalog doesn't exist there. Infuriating when you don't know to look for it.
Next, confirm your OAuth app is requesting the msads.manage scope during authorization. If your app was written before mid-2022, it probably uses an older scope. Go to your OAuth consent flow configuration and update the scope string. After updating, force a new token authorization, don't just refresh the existing token, because the old token was issued under the old scope and won't carry the new permissions.
Finally, open Microsoft Merchant Center at ads.microsoft.com, navigate to your store, and confirm that your catalog shows "API enabled" in its status. If it doesn't, that's your problem right there.
dry-run query parameter appended to your endpoint URL. For example: https://content.api.bingads.microsoft.com/shopping/v9.1/bmc/{bmcMerchantId}/products/{itemId}?dry-run. This validates your request structure and returns real validation errors without writing anything to your live feed, so you can confirm your auth and payload formatting are correct before risking your active catalog.
If you're starting fresh, this is step zero, and you can't skip it. The Content API requires both a Microsoft Advertising account and a developer token issued specifically for the production environment. Neither is optional.
Head to https://ads.microsoft.com and sign in with your Microsoft account. If you don't have a Microsoft Advertising account yet, you'll see the option to sign up for one immediately after signing in. Click it and follow through the account creation flow. Don't create a throwaway account here, this account is going to be tied to your Merchant Center store and your billing, so use the one you actually intend to advertise from.
Once your Advertising account exists, get your developer token from the Microsoft Advertising Developer Portal. From inside your Advertising account, navigate to Tools > API Center > Developer Portal. Click Request Token and fill in the requested information about your integration.
Here's something the documentation underplays: if you're using the API to manage your own account only, your token arrives immediately. If you're building a tool that manages accounts for other advertisers, Microsoft will review your request manually and it can take up to five business days. Plan your launch timeline around that if you're building a multi-merchant integration.
Once you have your developer token, store it securely, in an environment variable or secrets manager, not hardcoded in your application. You'll pass it as the DeveloperToken request header on every API call. If this token is compromised, an attacker can interact with your entire Merchant Center catalog on your behalf.
When this step is complete, you should have: a live Microsoft Advertising account ID, a developer token string (it looks like a 30–40 character alphanumeric string), and access to sign in at ads.microsoft.com.
Authentication is where most Microsoft Advertising Shopping Content API integrations break. The API uses OAuth 2.0 via the Microsoft identity platform, the same auth system used by Bing Ads API, so if you've built integrations for those before, the flow will look familiar. But the msads.manage scope requirement changed things significantly in 2022 and a lot of older documentation still shows the pre-2022 scope.
Register your application in the Azure portal under Azure Active Directory > App registrations. During registration, set your redirect URI and note your Application (client) ID. You'll need this in your OAuth flow.
When constructing your authorization URL, include the msads.manage scope explicitly:
https://login.microsoftonline.com/common/oauth2/v2.0/authorize?
client_id=YOUR_CLIENT_ID&
response_type=code&
redirect_uri=YOUR_REDIRECT_URI&
scope=msads.manage+offline_access&
response_mode=queryThe offline_access scope is what gives you a refresh token so you're not forcing users to re-authorize every hour. Don't omit it.
After the user authorizes, exchange the authorization code for an access token at https://login.microsoftonline.com/common/oauth2/v2.0/token. Store the access token and refresh token your code receives. Access tokens expire, typically within one hour, so build in automatic refresh logic that exchanges your refresh token for a new access token before your current one expires. A lot of integrations forget this and then work great in testing but start returning 401 errors in production after the first hour.
If you're already using the Bing Ads SDK for .NET, Java, or Python for campaign management, you can use the SDK's built-in authentication helpers to get your access token. The Content API itself has no SDK interfaces, but the token the SDK generates works fine for Content API calls. That said, if you're not already using the SDK for other Advertising API work, don't install it just for auth, the OAuth flow above is straightforward enough to implement directly.
A successful authentication step produces an access_token value you can use immediately as your AuthenticationToken request header.
Before the Content API can serve your products in Shopping campaigns, your website has to be verified and claimed in Microsoft Merchant Center. This is a prerequisite that blocks everything else, even if your API authentication is perfect, your ads won't run if your domain isn't verified.
Go to Bing Webmaster Tools at https://www.bing.com/webmasters. Sign in with the same Microsoft account you use for Microsoft Advertising, this part is critical and is a common source of confusion. If you're signed into Webmaster Tools with a different Microsoft account than your Advertising account, the verification won't link properly to your MMC store.
In Webmaster Tools, add your website URL and choose your verification method. Microsoft gives you several options: adding a meta tag to your homepage, uploading an XML file to your server root, or adding a CNAME record to your DNS. The XML file method is often the quickest for most setups, just download the provided file and drop it in your web root, then click Verify.
After Webmaster Tools confirms verification, go to your Microsoft Merchant Center store settings and complete the domain claim process there. Verification and claiming are two separate steps, a lot of people verify in Webmaster Tools and then wonder why MMC is still showing the domain as unverified. You have to claim it from within MMC after verifying it in Webmaster Tools.
To navigate there: in Microsoft Advertising, go to Tools > Microsoft Merchant Center, select your store, then Business Settings > Store URL. Enter your URL and follow the claim prompts.
Once complete, your store settings should show a green verified status next to your domain. Only then does MMC actually trust that the products you're uploading via the Content API belong to a legitimate storefront that Microsoft can send buyers to.
If you don't have a Microsoft Merchant Center store yet, you need to create one before making any Content API calls. From Microsoft Advertising, navigate to Tools > Microsoft Merchant Center > Create Store. Walk through the store creation wizard, you'll provide your store name, store URL (must match your verified domain), and a few business details.
Here's what happens automatically when you create a store: Microsoft generates a default catalog for you and enables it for both API access and standard management. You don't have to do anything special to enable that default catalog for API use. But if you want to manage multiple catalogs, say, one for each product line or one for each country/language target, you'll need to create additional catalogs and configure them.
To add a new catalog via the Content API, use the Catalogs resource endpoint. Every catalog you create through the API is automatically API-enabled. To create a catalog via the MMC web interface instead: go to your store, click Catalog Management > Create Catalog, give it a name and set the feed settings, then save it.
Now, when you make product API calls, the default catalog receives all operations unless you specify otherwise. To target a specific non-default catalog, append the bmc-catalog-id query parameter to your request URL:
https://content.api.bingads.microsoft.com/shopping/v9.1/bmc/{bmcMerchantId}/products?bmc-catalog-id=YOUR_CATALOG_IDFind your catalog IDs in MMC under Catalog Management, each catalog listed there has a numeric ID. Write these down, or query them programmatically using the Catalogs resource GET endpoint.
One thing worth knowing: you can use both the API and FTP/SFTP to update the same catalog feed in certain configurations. If you're migrating from an existing FTP-based feed setup, you don't have to switch everything at once, though Microsoft's official guidance recommends eventually moving fully to one method to avoid conflicting updates.
This step saves a lot of headaches. Microsoft doesn't offer a dedicated sandbox environment for Content API testing. There's no test endpoint you can hammer with bad data without consequence. But Microsoft does provide the dry-run query parameter, which lets you test your integration against the real production API without modifying your live catalog data.
To use it, simply append ?dry-run to any Product or Inventory resource URL:
# Test a product insert without touching live data
POST https://content.api.bingads.microsoft.com/shopping/v9.1/bmc/{bmcMerchantId}/products?dry-run
# Test a batch operation in dry-run mode
POST https://content.api.bingads.microsoft.com/shopping/v9.1/bmc/{bmcMerchantId}/products/batch?dry-runDry-run mode returns real validation errors exactly as production would, so if your product payload is missing a required field or contains an invalid value, you'll see the error. What it won't do is persist any data or return an item ID on insert operations. That's by design: since nothing is stored, there's no ID to return.
Note that dry-run applies only to the Products and Inventory resources. It does not work on the Catalog resource, Catalog operations always affect live data.
Run a full batch of test inserts, updates, and deletes against dry-run first. Check that:
- Your authentication headers are accepted (no 401 errors)
- Your product payload structure passes validation (no 400 errors)
- Your catalog ID targeting is correct (no "catalog not found" errors)
- Your batch size is within limits (large batches are one of the key advantages of Content API over FTP, but there are documented per-request limits)
When dry-run runs cleanly with zero errors, remove the parameter and run your first real insert against the live catalog. Check your MMC store after a few minutes to confirm the products appear. That's your end-to-end validation that the integration is working correctly.
Advanced Troubleshooting
Diagnosing Content API Authentication Errors in Enterprise Environments
If you're running this integration inside a corporate network or on a domain-joined machine, there are a few additional failure modes that don't show up in standard setups. Proxy servers with SSL inspection can silently break OAuth token requests by intercepting the TLS handshake to login.microsoftonline.com. The request appears to succeed from the network's perspective, but the access token returned is invalid or empty because the certificate chain was modified in transit. If your 401 errors only happen in corporate environments but not on direct internet connections, this is almost certainly the cause. Work with your network team to whitelist login.microsoftonline.com and content.api.bingads.microsoft.com in your proxy's SSL inspection bypass list.
Diagnosing 403 Errors on Multi-Customer Management Scenarios
When you're managing catalogs on behalf of another advertiser, a 403 response almost always means one of the management headers is wrong or missing. Double-check three things: First, your CustomerId header must contain the customer ID of the account you're managing, not your own agency customer ID. Second, your CustomerAccountId must be an account ID that actually belongs to that customer. It doesn't matter which account you pick (any account under that customer works), but it has to genuinely belong to them. Third, confirm the customer has actually granted your agency proper access to their Microsoft Advertising account. Without the correct access grant on the customer's side, the API will reject your management headers even if everything else is right.
Investigating Catalog Status and Feed Processing Errors
The Content API offers the ability to download catalog status reports, which are essential for diagnosing why products you've uploaded aren't showing in Shopping campaigns. If products are being accepted by the API (no errors on insert) but not appearing in ads, the issue is almost always in feed processing, the product passed structural validation but failed business rule validation on Microsoft's back end. Pull the catalog status report for your store by querying the appropriate status resource endpoint and look for disapproval codes. Common ones include missing GTINs, mismatched pricing between your product page and the API payload, or policy violations on product descriptions.
Batch Operation Error Handling
Batch operations are one of the strongest features of Content API, you can bundle inserts, updates, and deletes into a single request instead of making individual API calls. But batch error handling is tricky: a failure on one item in a batch doesn't automatically fail the whole batch. The API processes each item in the batch independently and returns per-item status codes. If you're not reading per-item responses carefully, you might think a batch succeeded when actually 20% of your products failed silently. Always iterate the response items and log any that returned error status codes, not just whether the HTTP response was a 200.
Escalate to Microsoft Support if: your developer token request has been pending for more than five business days with no response; you're receiving 5xx server errors consistently across all endpoints; your store was suspended and you believe it was done in error; or your OAuth tokens are being rejected despite a correct msads.manage scope and valid client credentials. For catalog-level suspensions or policy issues, Microsoft Support is also the right channel, there's no API endpoint that can resolve those.
Prevention & Best Practices
Build Your Integration to Last
The biggest ongoing headache with Microsoft Advertising Shopping Content API integrations isn't the initial setup, it's keeping them running reliably over months and years. The most common failure mode I've seen in production integrations is token management. OAuth access tokens expire, and if your application doesn't handle token refresh automatically, your feed goes stale silently. Your Shopping campaigns keep running but serving outdated prices and availability, which costs you money on wasted clicks and potentially a ton of customer service headaches when buyers arrive at your site expecting a price that's changed.
Build token refresh into your integration from day one. Store both your access token and your refresh token. Before every batch of API calls, check whether your access token is within 5 minutes of expiry, and if so, exchange your refresh token for a new one before proceeding. Don't wait for a 401 to trigger a refresh, handle it proactively.
Also think carefully about which products truly need real-time updates via Content API versus which can tolerate a nightly FTP upload. The Content API's key advantage is incremental, near-real-time updates. If you're in a business where pricing fluctuates during the day, flash sales, stock-driven pricing, competitive matching, Content API's ability to update a single product's availability field in seconds is genuinely valuable. If your catalog is mostly static with weekly price changes, the FTP route may be simpler to maintain.
For large catalogs, lean heavily into batch operations. Sending individual insert or update requests for every product is inefficient and increases your risk of hitting rate limits. Batch together as many operations as the API allows per request, and process those batches asynchronously so a slow API response doesn't block your entire update pipeline.
- Implement automatic OAuth token refresh before every batch of API calls, never let a stale access token kill your feed mid-update
- Always test new product payload changes with
?dry-runbefore deploying to production, catch validation errors before they affect your live catalog - Pull and review catalog status reports weekly to catch silently rejected products that aren't surfacing in your Shopping campaigns
- Use the
bmc-catalog-idparameter explicitly on every API call, even when targeting the default catalog, it prevents catalog routing bugs when you add new catalogs later
Frequently Asked Questions
Who should actually use the Microsoft Advertising Shopping Content API vs just uploading a feed file?
The Content API is the right choice if you're currently using Google's Content API (the migration is straightforward), if your product catalog has a large number of items, or if you can actually integrate the API with your existing inventory management systems. If your catalog is small, say, fewer than a few hundred products, or you don't have developer resources to maintain an API integration, the FTP/SFTP feed upload is simpler and perfectly adequate. The API's real value is in incremental updates: being able to change a price or flip availability to "out of stock" in near real-time without re-uploading your entire feed. If that doesn't matter to your business, the extra complexity isn't worth it.
Where exactly do I put my developer token and access token in API requests?
Both go in the HTTP request headers, not in the URL, not in the body. Your developer token goes in the DeveloperToken header, and your OAuth access token goes in the AuthenticationToken header. Every single Content API request must include both. If you're managing someone else's account, you also need CustomerId (the customer's ID) and CustomerAccountId (any account ID belonging to that customer) as additional headers. Missing any of these will get you a 401 or 403 depending on which one is absent.
How do I configure Microsoft Merchant Center to work with the Content API?
There are three required steps before your first API call can succeed. First, verify and claim your website URL, do this in Bing Webmaster Tools, then complete the claim process inside Microsoft Merchant Center using the same Microsoft account for both. Second, create a Microsoft Merchant Center store at ads.microsoft.com. Third, confirm that your catalog shows as API-enabled, this happens automatically when you create a store or add catalogs through the API. Any catalog created through MMC or the Catalogs resource is automatically available for API management. If you want to target a specific catalog rather than the default, pass the bmc-catalog-id query parameter in your API requests.
Can I use both the Content API and FTP/SFTP to update the same catalog?
Yes, in certain configurations Microsoft does allow you to use both the API and FTP/SFTP to update the same catalog feed. That said, mixing update methods on the same catalog can cause unpredictable results if both pipelines push conflicting data at the same time, for example, if your FTP feed overwrites an API-applied price change. If you're in a migration period moving from FTP to API, this flexibility is genuinely useful. But for steady-state operations, pick one method per catalog and stick with it. Microsoft's documentation covers the specifics of the hybrid approach in the "Can I Use the API and FTP/SFTP?" section of their official docs.
Is there a sandbox environment for testing Microsoft Advertising Content API?
No, Microsoft does not provide a dedicated sandbox environment for Content API. This is different from what some other API platforms offer, and it catches a lot of developers off guard. What Microsoft provides instead is the dry-run query parameter, which you append to any Product or Inventory resource URL. Dry-run runs your request against the real production endpoint, validates your payload and authentication, and returns any errors, but writes nothing to your live catalog. The main limitation: insert operations in dry-run don't return an ID, and the service won't generate secondary errors. Use dry-run aggressively while building your integration. Note that dry-run does not work for Catalog resource operations.
My Content API integration stopped working after mid-2022, what happened?
Starting June 1, 2022, Microsoft made multi-factor authentication mandatory for all users signing in through third-party applications using the Bing Ads API, Content API, and Hotel APIs. Part of this change requires applications to request user consent using the msads.manage OAuth scope. If your app was built before that date and you haven't updated it, your authentication will fail or behave unpredictably because your tokens were issued under the old scope. Update your OAuth authorization URL to include msads.manage in the scope parameter, then force a full re-authorization (not just a token refresh) to get a new token under the updated scope. The Microsoft identity platform's "Multi-factor authentication requirement guide" in the official docs covers the full migration steps.