Commerce REST API reference (private preview)

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

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.

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, default 10. The number of products returned depends on available matches. There's no pagination and no parameter for the number of offers per product.
  • language and region: two-character codes. location coordinates 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.
  • language and region: two-character codes. location coordinates 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.
  • language and region: 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.