Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
Note
Web IQ Commerce is available in private preview to a select group of Azure customers. During the private preview, usage is billed at $7.00 per 1,000 API calls. The API surface and contract may change.
Eligible customers can try the Commerce APIs in the Playground in the Web IQ Developer Portal. If you haven't used the Playground before, start with the Quickstart.
We'll expand access during the private preview; access isn't guaranteed. To request access or ask questions, open a Web IQ Support request, choose Authentication & Access as the problem type and API Key Set-up as the subtype, select Create a support request, and include your AppID (copy it from Profile Management in the Web IQ Developer Portal) or, if you don't have one yet, your company name and the name of your Web IQ resource.
The Web IQ Commerce APIs are Commerce Search, Offers, and Product Details. Commerce Search returns ranked products and seller offers for a product query. Use the available product, SKU, and offer identifiers with Offers. Product Details accepts product and SKU identifiers.
All three endpoints accept POST requests with a JSON body. Authenticate with an API key enabled for Commerce in the x-apikey header, or with a Microsoft Entra ID access token in the Authorization header. See Authentication for setup instructions.
Examples use fictional Contoso products, sellers, identifiers, URLs, and prices. Replace example identifiers with values from your Commerce Search response when making follow-up requests.
Request headers
| Header | Type | Description |
|---|---|---|
| x-apikey or Authorization | string | Your API key or Entra ID access token for authentication. |
| content-type | string | MIME type of the request body. Use application/json. |
Supported markets
During the private preview, the Commerce APIs support these combinations of language and region. Other combinations aren't supported.
| Market | language |
region |
|---|---|---|
| English (United States) | en |
US |
| Spanish (United States) | es |
US |
| English (Canada) | en |
CA |
| French (Canada) | fr |
CA |
| English (United Kingdom) | en |
GB |
| German (Germany) | de |
DE |
| French (France) | fr |
FR |
| English (Australia) | en |
AU |
| Japanese (Japan) | ja |
JP |
Offer links and attribution
For every offer you present, use its clickUrl exactly as returned in that response for every link or navigation to the offer, whether by a user or by an agent acting for the user. By default, clickUrl is a Microsoft-hosted redirect; Microsoft can also return a direct merchant URL. Use displayUrl only to identify the merchant or seller in your display or as model context, never as a link or navigation target. If an offer doesn't have a usable clickUrl, don't present the offer.
Treat clickUrl as opaque. The attribution parameter is required and can be inside the redirect, so it might not be visible. Don't strip, rewrite, truncate, decode, or substitute the clickUrl or its attribution parameter, and don't bypass its redirects or add a parameter yourself. You can wrap a clickUrl in your own tracking or redirect link only if it passes the original clickUrl through unaltered. Don't reuse a clickUrl for a different response, query, user, or purpose, including through a cache. An end user's own sharing or forwarding isn't reuse.
Build each link in application code from the clickUrl in the response, rather than having a model reproduce it. For the terms that apply, see Exhibit B of the Web IQ Terms of Use.
Commerce Search
Endpoint: POST https://api.microsoft.ai/v3/search/commerce/products
Returns ranked products and seller offers for a product query. Use the available product, SKU, and offer identifiers with Offers. Product Details accepts product and SKU identifiers.
Commerce Search sample request
curl -X POST "https://api.microsoft.ai/v3/search/commerce/products" \
-H "x-apikey: <Your API key>" \
-H "content-type: application/json" \
-d '{
"query": "Contoso wireless headphones",
"maxResults": 1,
"language": "en",
"region": "US",
"location": "lat:37.7749;long:-122.4194"
}'
Commerce Search parameters
| Parameter | Required | Type | Default | Description |
|---|---|---|---|---|
query |
Yes | string | - | Product search query that isn't blank. Maximum length is 1,000 characters. |
maxResults |
No | integer | 10 |
Maximum number of products to return, from 1 to 50. |
language |
No | string | en |
Two-letter ISO 639-1 result language. See Supported markets. |
region |
No | string | US |
Two-letter country or region code. See Supported markets. |
location |
No | string | - | Location in lat:<latitude>;long:<longitude> format, for example lat:37.7749;long:-122.4194. Latitude must be from -90 to 90, and longitude from -180 to 180. |
Commerce Search response
Returns a CommerceResponse with ranked products and their offers. If no products match, the response is 200 OK with an empty products array.
Example 200 OK response (excerpt):
{
"products": [
{
"offers": [
{
"id": "100000000001",
"name": "Contoso Wireless Headphones",
"seller": {
"name": "Contoso Electronics",
"logoUrl": "https://contoso.example/logo.png"
},
"price": { "listPrice": 10000, "offeredPrice": 9000, "currency": "USD" }
}
],
"id": "PG_00000000000000000000000000000001",
"skuId": "00000000000000000000000000000001"
}
],
"traceId": "<trace-id>"
}
Commerce Search errors
A missing, blank, or overlong query, an out-of-range maxResults, a language or region that isn't two characters, or an invalid location returns 400 (HandlerInvalidInput). Service failures return 500 (InternalServerError). For authentication, authorization, format, and quota errors, see Errors.
Commerce Search limits
query: 1 to 1,000 characters, and not only whitespace.maxResults: 1 to 50, default10. The number of products returned depends on available matches. There's no pagination and no parameter for the number of offers per product.languageandregion: two-character codes.locationcoordinates must be within the ranges in the parameters table.- The rate limits and daily quota of your app profile (AppID) also apply.
Offers
Endpoint: POST https://api.microsoft.ai/v3/fetch/commerce/products/offers
Returns eligible seller offers for one product, SKU, or representative offer from Commerce Search. It returns seller offers, not product-level feedback or price history.
Offers sample request
curl -X POST "https://api.microsoft.ai/v3/fetch/commerce/products/offers" \
-H "x-apikey: <Your API key>" \
-H "content-type: application/json" \
-d '{
"productId": "PG_00000000000000000000000000000001",
"skuId": "00000000000000000000000000000001",
"offerId": "100000000001",
"language": "en",
"region": "US"
}'
Offers parameters
Send all available product, SKU, and offer identifiers for the selected product from the Commerce Search response. If only one identifier is returned, send that identifier. At least one identifier that isn't blank is required; a request without one returns 400 (HandlerInvalidInput).
| Parameter | Required | Type | Default | Description |
|---|---|---|---|---|
productId |
Conditional | string | - | Product id returned by Commerce Search. Maximum 1,000 characters. |
skuId |
Conditional | string | - | Product skuId returned by Commerce Search. Maximum 1,000 characters. |
offerId |
Conditional | string | - | Representative offer id returned by Commerce Search. Maximum 1,000 characters. |
language |
No | string | en |
Two-letter ISO 639-1 result language. See Supported markets. |
region |
No | string | US |
Two-letter country or region code. See Supported markets. |
location |
No | string | - | Location in lat:<latitude>;long:<longitude> format. Latitude must be from -90 to 90, and longitude from -180 to 180. |
Offers response
CommerceOffersResponse
| Field | Type | Description |
|---|---|---|
offers |
array of CommerceOffer | Primary or representative offers first, followed by additional offers. |
traceId |
string | Request trace identifier for debugging and correlation. |
For the offer fields, see CommerceOffer, CommerceOfferImage, CommerceInstallmentInfo, and Supporting objects. Unknown identifiers return 200 OK with an empty offers array.
Example 200 OK response (excerpt):
{
"offers": [
{
"id": "100000000001",
"name": "Contoso Wireless Headphones",
"seller": {
"name": "Contoso Electronics",
"logoUrl": "https://contoso.example/logo.png"
},
"price": { "listPrice": 10000, "offeredPrice": 9000, "currency": "USD" }
}
],
"traceId": "<trace-id>"
}
Offers errors
A missing or blank identifier, an identifier longer than 1,000 characters, a language or region that isn't two characters, or an invalid location returns 400 (HandlerInvalidInput). Unknown identifiers return 200 OK with an empty offers array. Service failures return 500 (InternalServerError). See Errors.
Offers limits
- One product, SKU, or representative-offer lookup per request; batch lookups aren't supported. Each identifier is limited to 1,000 characters.
- There's no
maxResults, offset, or cursor parameter. The number of offers depends on availability. languageandregion: two-character codes.locationcoordinates must be within the ranges in the parameters table.- The rate limits and daily quota of your app profile (AppID) also apply.
Product Details
Endpoint: POST https://api.microsoft.ai/v3/fetch/commerce/products/details
Returns the product title (name), description, and aggregate rating for a product ID, a SKU ID, or both, from Commerce Search. The description is included when available.
Product Details sample request
curl -X POST "https://api.microsoft.ai/v3/fetch/commerce/products/details" \
-H "x-apikey: <Your API key>" \
-H "content-type: application/json" \
-d '{
"productId": "PG_00000000000000000000000000000002",
"skuId": "00000000000000000000000000000002",
"language": "en",
"region": "US"
}'
Product Details parameters
At least one productId or skuId that isn't blank is required, and you can send both. offerId isn't an alternative: a request with only an offer ID fails validation.
| Parameter | Required | Type | Default | Description |
|---|---|---|---|---|
productId |
Conditional | string | - | Product id from Commerce Search. Required when no skuId is sent. Maximum 1,000 characters. |
skuId |
Conditional | string | - | SKU ID from Commerce Search. Required when no productId is sent. Maximum 1,000 characters. |
language |
No | string | en |
Two-letter language code. If omitted or null, the default is used. See Supported markets. |
region |
No | string | US |
Two-letter region code for the product lookup. If omitted or null, the default is used. See Supported markets. |
Product Details response
CommerceProductDetailsResponse
| Field | Type | Description |
|---|---|---|
products |
array of CommerceProductDetails | Zero or one matching product. Batch lookups aren't supported. |
traceId |
string | Request trace identifier. |
CommerceProductDetails
| Field | Type | Description |
|---|---|---|
id |
string | Product identifier across variants, matching Commerce Search. |
name |
string | Product title, when available. |
description |
string | Product description, when available. |
rating |
CommerceRating | Product average rating and rating count, on a 1 to 5 scale. |
CommerceRating
The rating object is omitted when no rating is available.
| Field | Type | Description |
|---|---|---|
value |
number | Product average rating, rounded to two decimal places. |
scaleMin |
number | Bottom of the rating scale (1). |
scaleMax |
number | Top of the rating scale (5). |
count |
integer | Number of ratings for the product. A count of zero is returned as 0. |
Unknown products return 200 OK with an empty products array.
Example 200 OK response:
{
"products": [
{
"id": "PG_00000000000000000000000000000002",
"name": "Contoso Wireless Earbuds",
"description": "Illustrative wireless in-ear headphones",
"rating": { "value": 4.2, "scaleMin": 1, "scaleMax": 5, "count": 42 }
}
],
"traceId": "<trace-id>"
}
Product Details errors
A missing or blank product or SKU identifier, an identifier longer than 1,000 characters, or a language or region that isn't two characters returns 400 (HandlerInvalidInput). Service failures return 500 (InternalServerError). See Errors.
Product Details limits
- At least one product or SKU identifier, up to 1,000 characters each. Batch lookups and lookups by offer ID only aren't supported.
languageandregion: two-character codes.- The rate limits and daily quota of your app profile (AppID) also apply.
Response objects
These objects are returned by Commerce Search and Offers.
CommerceResponse
| Field | Type | Description |
|---|---|---|
products |
array of CommerceProduct | Products in rank order. |
traceId |
string | Request trace identifier for debugging and correlation. |
CommerceProduct
| Field | Type | Description |
|---|---|---|
id |
string | Product identifier across variants. |
skuId |
string | Catalog SKU identifier. |
offers |
array of CommerceOffer | Primary seller offers. |
CommerceOffer
| Field | Type | Description |
|---|---|---|
id |
string | Offer identifier. |
name |
string | Seller title. |
description |
string | Seller description. |
specifications |
array of CommerceSpecification |
Offer-level specifications and selected attributes. Duplicates and source order are preserved. See Supporting objects. |
seller |
CommerceSeller |
Merchant details. See Supporting objects. |
price |
CommerceOfferPrice |
Offer pricing in ISO 4217 minor units. offeredPrice falls back to listPrice when no discount price is present. See Supporting objects. |
displayUrl |
string | Merchant or seller URL, for display or model context only. Don't use it as a link or navigation target. |
clickUrl |
string | Destination for every link or navigation to the offer. Use it exactly as returned. See Offer links and attribution. |
images |
array of CommerceOfferImage | Offer images. |
installmentInfo |
CommerceInstallmentInfo | Installment payment details. |
shippingInfo |
string | Shipping information, as readable text. |
condition |
string | Seller-provided condition of the offered item. |
CommerceOfferImage
| Field | Type | Description |
|---|---|---|
url |
string | Image URL. |
CommerceInstallmentInfo
| Field | Type | Description |
|---|---|---|
description |
string | Description of the installment plan, as readable text. |
downPayment |
CommercePrice |
Amount required up front. See Supporting objects. |
monthlyPayment |
CommercePrice |
Monthly installment payment. See Supporting objects. |
months |
integer | Number of months. |
Supporting objects
Prices are integers in ISO 4217 minor units of the currency. For example, 10000 with currency USD is $100.00.
| Object | Field | Type | Description |
|---|---|---|---|
CommerceOfferPrice |
listPrice |
integer | Original price in ISO 4217 minor units. |
CommerceOfferPrice |
offeredPrice |
integer | Current price in ISO 4217 minor units. Falls back to listPrice when no discount price is available. |
CommerceOfferPrice |
currency |
string | ISO 4217 currency code. |
CommercePrice |
amount |
integer | Payment amount in ISO 4217 minor units. |
CommercePrice |
currency |
string | ISO 4217 currency code. |
CommerceSeller |
name |
string | Merchant display name. |
CommerceSeller |
logoUrl |
string | Merchant logo URL. |
CommerceSpecification |
name |
string | Offer attribute name. |
CommerceSpecification |
values |
array of string | Attribute display values, preserving duplicates and source order. |
Errors
These errors apply to all three endpoints. The validation and empty-result behavior of each endpoint is described in its own section.
| HTTP status | Error code | Meaning and action |
|---|---|---|
400 |
RequestInvalidFormat, HandlerInvalidInput |
Malformed JSON, or request parameters that are missing or invalid. Correct the request using the endpoint's parameters table and limits. |
401 |
Authentication errors, such as AuthNoToken or AuthInvalidApiKey |
Credentials are missing, invalid, or expired. Authenticate again with valid credentials. |
403 |
AuthUnauthorizedService |
The caller isn't authorized to access the requested resource. If your app profile isn't enabled for Commerce, request access as described at the top of this page. |
405 |
MethodNotAllowed |
Use POST, not GET. |
415 |
RequestUnsupportedMediaType |
Send content-type: application/json. |
429 |
AuthUserThrottled, AuthUserDailyUsageExceeded |
The rate limit or daily quota of your app profile (AppID) was exceeded. Wait for the time in retryAfter before you retry. |
500 |
InternalServerError |
The service couldn't complete the request. Retry after the indicated delay, and include the traceId when you contact support. |
Error response
Errors use the shared error response structure.
| Field | Type | Description |
|---|---|---|
errorCode |
string | Machine-readable error code. |
errorCategory |
string | UserError or SystemError. |
userMessage |
string | Readable explanation of the error. |
technicalDetails |
string | Optional diagnostic details. |
retryAfter |
string | Optional retry delay in seconds, followed by an s suffix (for example, "60s"). |
requestId |
string | Optional request identifier. |
traceId |
string | Optional distributed trace identifier for support. |
Error example
A Commerce Search request without query:
curl -X POST "https://api.microsoft.ai/v3/search/commerce/products" \
-H "x-apikey: <Your API key>" \
-H "content-type: application/json" \
-d '{}'
400 Bad Request response:
{
"errorCode": "HandlerInvalidInput",
"errorCategory": "UserError",
"userMessage": "Invalid input provided. Please check your request parameters.",
"technicalDetails": "query is required",
"traceId": "<trace-id>"
}
Rate limits
All three endpoints use the rate limits and daily quota of your Web IQ AppID (15 queries per second by default), shared with the other Web IQ APIs the AppID calls. A 429 response includes the retry delay in retryAfter. Daily quotas reset at 00:00 UTC. For retry guidance, see Error handling.