Commerce API & MCP › API reference

Commerce REST API Reference

Build market-wide Commerce data workflows -- product discovery and pricing -- against the four canonical operations at https://api.nesika.ai/api/v1. Authenticate canonical examples with a Developer Project REST API key.

Open interactive API reference OpenAPI spec (JSON)

Developer Project REST API key

From the selected Developer Project, create a key with credential_kind=api_key, then send X-API-Key: $NESIKA_API_KEY with a client-generated Idempotency-Key on every request.

Canonical v1 request

curl -X POST "https://api.nesika.ai/api/v1/commerce/search-products" \
  -H "X-API-Key: $NESIKA_API_KEY" \
  -H "Idempotency-Key: 8f14e45f-2d3b-4f1c-9a71-8f2c6f2b9c31" \
  -H "Content-Type: application/json" \
  -d '{ "market": "AU", "query": "iPhone 16" }'

The four Commerce operations

These are the only Commerce REST operations. Each has a matching Commerce MCP tool of the same name. Use generated OpenAPI documentation for complete request and response schemas.

POST https://api.nesika.ai/api/v1/commerce/search-products

search_products

Searches retailer product candidates through the Commerce engine.

POST https://api.nesika.ai/api/v1/commerce/resolve-product

resolve_product

Matches a supplied product to an exact identifier -- a GTIN or a merchant-scoped product ID -- and returns alternatives and ambiguity notes when no exact match is confirmed.

POST https://api.nesika.ai/api/v1/commerce/find-offers

find_offers

Finds retailer offers for a product identity.

POST https://api.nesika.ai/api/v1/commerce/deep-search

deep_search

Performs bounded deep product research when standard search is insufficient.

Errors

When a request or MCP tool call fails, the response carries an error code, a plain message and a next step. MCP tools return the code in error_code and, in lowercase, in structuredContent.error.code with next_action. Quote the request_id when you contact support.

AUTHENTICATION_REQUIRED: The credential is missing, invalid or expired. Reconnect the connector or send a valid key.
INSUFFICIENT_SCOPE: The credential's scopes do not allow this action. Reconnect and grant the scope named in required_scope.
ROLE_FORBIDDEN: Your workspace role does not allow this action. Ask a workspace admin to make the change or change your role.
INSUFFICIENT_PERMISSION: The connection lacks the permission named in required_permission. Ask a workspace admin for it.
NOT_A_RETAIL_WORKSPACE_CREDENTIAL: A Developer Project credential was used on the Retail Workspace MCP. Use a Retail Workspace credential, or the Commerce MCP.
RESOURCE_NOT_FOUND: The product, scan or other record does not exist in this workspace. List it with the matching read tool and use an id it returns.
INVALID_REQUEST / VALIDATION_FAILED: Some arguments are missing or invalid. Fix the fields listed in invalid_fields and try again.
QUOTA_EXCEEDED: The workspace or project reached a plan limit for this action. Wait for the next period or review the plan.
RATE_LIMIT_EXCEEDED: Too many requests in a short time. Wait retryAfterSeconds and try again.
PREVIEW_STALE / PREVIEW_EXPIRED: The preview no longer matches the data, or it expired. Run the preview tool again and apply the new preview_id.
OUTCOME_UNKNOWN: A change got no answer, so it may have been applied. Read the record to check before trying again.
UPSTREAM_TIMEOUT / SERVICE_UNAVAILABLE: Nesika did not answer in time or is briefly unavailable. Nothing was changed; try again shortly.
UPSTREAM_AUTHORIZATION_UNAVAILABLE: Nesika could not confirm your access right now. Try again shortly; reconnect if it keeps failing.
INTERNAL_ERROR: The request could not be completed. Try again later, and quote the request_id if it keeps failing.

Need native tools instead of REST calls?

Commerce MCP is a separate public developer surface with four focused tools, its own endpoint, and a separate Commerce MCP credential. A REST API key cannot connect it.

View Commerce MCP