Commerce MCP

Tools reference

Generated from the live tool registry: the same names, schemas and annotations tools/list returns.

About these tools#

tools/list returns only the tools your scopes allow. See the scope table in Authentication and access.
Every tool is read-only and has the same annotations. Each lists noauth and oauth2 security schemes: no tool needs sign-in.
Successful calls return structuredContent matching the tool's output schema, and the same JSON as text in content. Errors are described in Limits and errors.
inventory_quantity appears only for callers with inventory:read, which only API keys can carry.
Examples are real responses from the demo store, captured on 2026-09-27 as an anonymous call to https://app.aiptimise.com/api/mcp/p/openai. Timestamps and IDs in your responses will differ.

search_products get_store_info get_live_price_and_inventory get_active_promotions get_loyalty_program get_aiptimise_product_data get_product_variants

search_products#

Search productscatalog:readreadOnlyHint: truedestructiveHint: falseidempotentHint: trueopenWorldHint: false

Finds products of participating merchants that match a shopper's need. Put the shopper's words (a need, use case, question or product type) in query; it supports "quoted phrases", OR and -exclusions. Price, currency, stock and attribute values are exact filters applied to each variant. Searches every participating store unless store_id is given. Returns a short ranked list with each product's best matching variant, its price and availability as of the last catalog sync, a storefront link, and verbatim excerpts labelled with the field they came from. match is any_term when no product contained every word, so results are a looser match. Use get_live_price_and_inventory to confirm an offer and get_aiptimise_product_data for full detail.

Parameters

Name	Type	Required	Description
`query`	string	no	What the shopper wants, in their words (e.g. 'washable rug for a home with pets')at most 200 characters
`store_id`	string (UUID)	no	Optional: search only this store (Aiptimise public store ID)
`min_price`	number	no	≥ 0
`max_price`	number	no	> 0
`currency`	string	no	ISO 4217 currency code; required with min_price or max_pricepattern ^[A-Za-z]{3}$
`in_stock`	boolean	no	true: only variants in stock at the last catalog sync
`brand`	string	no	1–100 characters
`category`	string	no	Matches part of the category path1–100 characters
`material`	string	no	Matches part of the material1–100 characters
`color`	string	no	1–100 characters
`size`	string	no	1–100 characters
`gender`	string	no	one of: male, female, unisex
`condition`	string	no	one of: new, refurbished, used
`attributes`	map of string	no	Variant options that must match exactly, e.g. {"Size": "8x10"}keys 1–50 characters · values 1–100 characters
`limit`	integer	no	Results to return (default 5, max 10)≥ 1 · ≤ 10

Output fields (21)

Field	Type	Always present
`store_id`	string (UUID)	no
`match`	stringone of: all_terms, any_term, filters	yes
`result_count`	integer	yes
`results`	object[]	yes
`results[].rank`	integer	yes
`results[].store`	object	yes
`results[].store.store_id`	string (UUID)	yes
`results[].store.name`	string	yes
`results[].product_id`	string	yes
`results[].variant_id`	string	yes
`results[].title`	string	yes
`results[].price`	money	yes
`results[].list_price`	money	no
`results[].availability`	string	yes
`results[].product_url`	string	yes
`results[].image_url`	string	no
`results[].brand`	string	no
`results[].evidence`	object[]	yes
`results[].evidence[].field`	stringone of: use_case, q_and_a, summary, highlight, description	yes
`results[].evidence[].snippet`	string	yes
`results[].as_of`	string (date-time)	yes

Example

Request (tools/call)

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search_products",
    "arguments": {
      "query": "waterproof rain jacket for hiking",
      "max_price": 200,
      "currency": "USD",
      "limit": 2
    }
  }
}

Response: result.structuredContent

{
  "match": "all_terms",
  "result_count": 1,
  "results": [
    {
      "rank": 1,
      "store": {
        "store_id": "edab46c9-76c6-4eb5-92dd-f593ed4bd9ad",
        "name": "Aiptimise Demo Store"
      },
      "product_id": "demo-summit-rain-jacket",
      "variant_id": "demo-summit-rain-jacket:demo-variant-1-1",
      "title": "Summit 3-Layer Rain Jacket - S / Glacier Blue",
      "price": {
        "amount": "189.00",
        "currency": "USD"
      },
      "availability": "in_stock",
      "product_url": "https://demo.aiptimise.com/products/summit-rain-jacket?variant=demo-variant-1-1&utm_source=chatgpt.com&utm_medium=ai_agent&utm_campaign=aiptimise_mcp&utm_content=42335a18-4a84-473a-b318-b1b93b03637c",
      "image_url": "https://demo.aiptimise.com/images/summit-rain-jacket.jpg",
      "brand": "Aiptimise Demo Store",
      "evidence": [
        {
          "field": "summary",
          "snippet": "Summit 3-Layer **Rain** **Jacket** is a **waterproof**, breathable **hiking** shell with taped seams, pit zips and a packable design, rated 20,000 mm **waterproof**"
        },
        {
          "field": "use_case",
          "snippet": "Multi-day **hikes** in wet climates — Stays **waterproof** in sustained **rain** while pit zips vent heat on climbs"
        }
      ],
      "as_of": "2026-09-27T17:40:57.154Z"
    }
  ]
}

get_store_info#

Get store informationcatalog:readreadOnlyHint: truedestructiveHint: falseidempotentHint: trueopenWorldHint: false

Returns a participating store's seller name and website, market (country, currency, language and the countries it ships to), return, privacy and terms policy links, return window, shipping zones and rates, policy details (shipping, returns, warranty, payment) and loyalty program, as stated on the store's own pages. advertised_offers are store-wide offers stated on those pages; use get_active_promotions for promotions the merchant approved for agents.

Parameters

Name	Type	Required	Description
`store_id`	string (UUID)	yes	Aiptimise public store ID (UUID)

Output fields (26)

Field	Type	Always present
`store_id`	string (UUID)	yes
`name`	string	yes
`url`	string	yes
`description`	string	no
`market`	object	yes
`market.country`	string	yes
`market.currency`	string	yes
`market.locale`	string	yes
`market.ships_to`	string[]	yes
`policies`	object	yes
`policies.return_policy_url`	string	no
`policies.privacy_policy_url`	string	no
`policies.terms_of_service_url`	string	no
`policies.return_window_days`	integer	no
`policies.details`	object (free-form)[]	yes
`shipping_zones`	object[]	yes
`shipping_zones[].name`	string	yes
`shipping_zones[].countries`	string[]	yes
`shipping_zones[].rates`	object[]	yes
`shipping_zones[].rates[].service`	string	yes
`shipping_zones[].rates[].price`	money	no
`shipping_zones[].rates[].carrier_calculated`	boolean	yes
`shipping_zones[].rates[].min_order`	money	no
`advertised_offers`	object (free-form)[]	yes
`loyalty_program`	object (free-form) \| null	yes
`facts_as_of`	string (date-time)	no

Example

Request (tools/call)

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_store_info",
    "arguments": {
      "store_id": "edab46c9-76c6-4eb5-92dd-f593ed4bd9ad"
    }
  }
}

Response: result.structuredContent

{
  "store_id": "edab46c9-76c6-4eb5-92dd-f593ed4bd9ad",
  "name": "Aiptimise Demo Store",
  "url": "https://demo.aiptimise.com",
  "description": "Fictional outdoor-gear store used by the Aiptimise MCP sandbox and platform review.",
  "market": {
    "country": "US",
    "currency": "USD",
    "locale": "en-US",
    "ships_to": [
      "US"
    ]
  },
  "policies": {
    "return_policy_url": "https://demo.aiptimise.com/policies/refund-policy",
    "privacy_policy_url": "https://demo.aiptimise.com/policies/privacy-policy",
    "terms_of_service_url": "https://demo.aiptimise.com/policies/terms-of-service",
    "return_window_days": 30,
    "details": []
  },
  "shipping_zones": [
    {
      "name": "United States",
      "countries": [
        "US"
      ],
      "rates": [
        {
          "service": "Standard",
          "price": {
            "amount": "6.95",
            "currency": "USD"
          },
          "carrier_calculated": false
        },
        {
          "service": "Free standard",
          "price": {
            "amount": "0.00",
            "currency": "USD"
          },
          "carrier_calculated": false,
          "min_order": {
            "amount": "75.00",
            "currency": "USD"
          }
        },
        {
          "service": "Express",
          "price": {
            "amount": "19.95",
            "currency": "USD"
          },
          "carrier_calculated": false
        }
      ]
    }
  ],
  "advertised_offers": [],
  "loyalty_program": null
}

get_live_price_and_inventory#

Get live price and inventoryoffers:readreadOnlyHint: truedestructiveHint: falseidempotentHint: trueopenWorldHint: false

Returns the current price, availability and product URL for one catalog item of a participating merchant, with the time the data was checked. A product sold in several variants requires variant_id; the error lists the valid IDs.

Parameters

Name	Type	Required	Description
`store_id`	string (UUID)	yes	Aiptimise public store ID (UUID)
`product_id`	string	yes	Product ID: the stable catalog item ID from a merchant feed, or the Aiptimise public product ID1–255 characters
`variant_id`	string	no	Stable variant item ID, as returned by get_product_variants1–255 characters

Output fields (12)

Field	Type	Always present
`store_id`	string (UUID)	yes
`product_id`	string	yes
`variant_id`	string	yes
`title`	string	yes
`price`	money	yes
`list_price`	money	no
`availability`	string	yes
`inventory_quantity`	number	no
`product_url`	string	yes
`as_of`	string (date-time)	yes
`source`	stringone of: live, snapshot	yes
`valid_until`	string (date-time)	no

Example

Request (tools/call)

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_live_price_and_inventory",
    "arguments": {
      "store_id": "edab46c9-76c6-4eb5-92dd-f593ed4bd9ad",
      "product_id": "demo-summit-rain-jacket",
      "variant_id": "demo-summit-rain-jacket:demo-variant-1-2"
    }
  }
}

Response: result.structuredContent

{
  "store_id": "edab46c9-76c6-4eb5-92dd-f593ed4bd9ad",
  "product_id": "demo-summit-rain-jacket",
  "variant_id": "demo-summit-rain-jacket:demo-variant-1-2",
  "title": "Summit 3-Layer Rain Jacket - M / Glacier Blue",
  "price": {
    "amount": "189.00",
    "currency": "USD"
  },
  "availability": "in_stock",
  "product_url": "https://demo.aiptimise.com/products/summit-rain-jacket?variant=demo-variant-1-2&utm_source=chatgpt.com&utm_medium=ai_agent&utm_campaign=aiptimise_mcp&utm_content=42335a18-4a84-473a-b318-b1b93b03637c",
  "as_of": "2026-09-27T17:40:57.154Z",
  "source": "snapshot"
}

get_active_promotions#

Get active promotionspromotions:readreadOnlyHint: truedestructiveHint: falseidempotentHint: trueopenWorldHint: false

Returns the merchant-approved promotions currently running for a participating store, optionally narrowed to one product. Each promotion carries its benefit, active period and the catalog IDs it applies to; an empty applies_to means it covers the whole store.

Parameters

Name	Type	Required	Description
`store_id`	string (UUID)	yes	Aiptimise public store ID (UUID)
`product_id`	string	no	Optional product ID; omit to list every active store promotion1–255 characters
`variant_id`	string	no	Optional stable variant item ID of product_id (requires product_id), as returned by get_product_variants1–255 characters

Output fields (17)

Field	Type	Always present
`store_id`	string (UUID)	yes
`product_id`	string	no
`variant_id`	string	no
`promotions`	object[]	yes
`promotions[].id`	string	yes
`promotions[].title`	string	yes
`promotions[].description`	object	no
`promotions[].description.plain`	string	yes
`promotions[].status`	stringone of: draft, scheduled, active, expired, disabled	no
`promotions[].active_period`	object	yes
`promotions[].active_period.start_time`	string (date-time)	yes
`promotions[].active_period.end_time`	string (date-time)	yes
`promotions[].benefits`	object (type: amount_off \| percent_off \| free_shipping)[]	yes
`promotions[].applies_to`	object[]	no
`promotions[].applies_to[].product_id`	string	yes
`promotions[].applies_to[].variant_ids`	string[]	no
`promotions[].url`	string	no

Example

Request (tools/call)

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_active_promotions",
    "arguments": {
      "store_id": "edab46c9-76c6-4eb5-92dd-f593ed4bd9ad",
      "product_id": "demo-summit-rain-jacket"
    }
  }
}

Response: result.structuredContent

{
  "store_id": "edab46c9-76c6-4eb5-92dd-f593ed4bd9ad",
  "product_id": "demo-summit-rain-jacket",
  "promotions": [
    {
      "id": "demo-welcome-10",
      "title": "10% off your first order for Trail Rewards members",
      "description": {
        "plain": "Join Trail Rewards (free) and get 10% off your first order."
      },
      "status": "active",
      "active_period": {
        "start_time": "2026-01-01T00:00:00.000Z",
        "end_time": "2030-12-31T23:59:59.000Z"
      },
      "benefits": [
        {
          "type": "percent_off",
          "percent_off": 10
        }
      ],
      "applies_to": [],
      "url": "https://demo.aiptimise.com/pages/offers"
    },
    {
      "id": "demo-free-shipping-75",
      "title": "Free shipping on orders over $75",
      "description": {
        "plain": "Free standard shipping to the US on orders over $75."
      },
      "status": "active",
      "active_period": {
        "start_time": "2026-01-01T00:00:00.000Z",
        "end_time": "2030-12-31T23:59:59.000Z"
      },
      "benefits": [
        {
          "type": "free_shipping"
        }
      ],
      "applies_to": [],
      "url": "https://demo.aiptimise.com/pages/offers"
    },
    {
      "id": "demo-rain-jacket-20",
      "title": "$20 off the Summit 3-Layer Rain Jacket",
      "description": {
        "plain": "Save $20 on the Summit rain jacket in every size and color."
      },
      "status": "active",
      "active_period": {
        "start_time": "2026-01-01T00:00:00.000Z",
        "end_time": "2030-12-31T23:59:59.000Z"
      },
      "benefits": [
        {
          "type": "amount_off",
          "amount_off": {
            "amount": 2000,
            "currency": "USD"
          }
        }
      ],
      "applies_to": [
        {
          "product_id": "demo-summit-rain-jacket"
        }
      ],
      "url": "https://demo.aiptimise.com/pages/offers"
    }
  ]
}

get_loyalty_program#

Get loyalty program detailsloyalty:readreadOnlyHint: truedestructiveHint: falseidempotentHint: trueopenWorldHint: false

Returns the loyalty program, points and tiers a participating merchant publishes for one product. Fields are merchant-authored and free-form; a product with no loyalty content returns empty values. No shopper account data is involved.

Parameters

Name	Type	Required	Description
`store_id`	string (UUID)	yes	Aiptimise public store ID (UUID)
`product_id`	string	yes	Product ID: the stable catalog item ID from a merchant feed, or the Aiptimise public product ID1–255 characters

Output fields (5)

Field	Type	Always present
`store_id`	string (UUID)	yes
`product_id`	string	yes
`program`	object (free-form) \| null	yes
`points`	object (free-form) \| null	yes
`programs`	object (free-form)[]	yes

Example

Request (tools/call)

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_loyalty_program",
    "arguments": {
      "store_id": "edab46c9-76c6-4eb5-92dd-f593ed4bd9ad",
      "product_id": "demo-trekker-45-backpack"
    }
  }
}

Response: result.structuredContent

{
  "store_id": "edab46c9-76c6-4eb5-92dd-f593ed4bd9ad",
  "product_id": "demo-trekker-45-backpack",
  "program": {
    "name": "Trail Rewards",
    "tiers": [
      {
        "name": "Explorer",
        "perks": [
          "Birthday bonus of 50 points"
        ],
        "threshold_points": 0
      },
      {
        "name": "Summit",
        "perks": [
          "Free express shipping",
          "Early access to new gear"
        ],
        "threshold_points": 1000
      }
    ],
    "terms_url": "https://demo.aiptimise.com/pages/trail-rewards",
    "description": "Earn 1 point per dollar spent. Every 100 points is worth $5 off a future order."
  },
  "points": {
    "basis": "1 point per $1 spent",
    "program": "Trail Rewards",
    "points_earned": 199
  },
  "programs": []
}

get_aiptimise_product_data#

Get product detailscatalog:readreadOnlyHint: truedestructiveHint: falseidempotentHint: trueopenWorldHint: false

Returns the full Aiptimise view of one product of a participating merchant: the schema.org Product JSON-LD published to AI crawlers, plus enriched data (answer-engine summary, highlights, Q&A, use cases, reviews and review summary, promotions, policies, loyalty, optimized copy).

Parameters

Name	Type	Required	Description
`store_id`	string (UUID)	yes	Aiptimise public store ID (UUID)
`product_id`	string	yes	Product ID: the stable catalog item ID from a merchant feed, or the Aiptimise public product ID1–255 characters

Output fields (18)

Field	Type	Always present
`store_id`	string (UUID)	yes
`product_id`	string	yes
`json_ld`	object (free-form)	yes
`enriched_data`	object	yes
`enriched_data.answer_engine_summary`	string \| null	yes
`enriched_data.product_highlights`	string[]	no
`enriched_data.q_and_a`	object[]	yes
`enriched_data.q_and_a[].q`	string	yes
`enriched_data.q_and_a[].a`	string	yes
`enriched_data.optimized_title`	string \| null	yes
`enriched_data.optimized_description`	string \| null	yes
`enriched_data.use_cases`	object (free-form)[]	yes
`enriched_data.reviews`	object (free-form)[]	yes
`enriched_data.review_summary`	object (free-form) \| null	yes
`enriched_data.promotions`	object (free-form)[]	yes
`enriched_data.policies`	object (free-form)[]	yes
`enriched_data.loyalty`	object (free-form) \| null	yes
`variant_count`	integer	yes

Example

Request (tools/call)

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_aiptimise_product_data",
    "arguments": {
      "store_id": "edab46c9-76c6-4eb5-92dd-f593ed4bd9ad",
      "product_id": "demo-ridge-merino-base-layer"
    }
  }
}

Response: result.structuredContent

JSON

{
  "store_id": "edab46c9-76c6-4eb5-92dd-f593ed4bd9ad",
  "product_id": "demo-ridge-merino-base-layer",
  "json_ld": {
    "@context": "https://schema.org",
    "@type": "ProductGroup",
    "name": "Ridge Merino Base Layer Top",
    "productGroupID": "demo-ridge-merino-base-layer",
    "variesBy": [
      "Size"
    ],
    "offers": {
      "@type": "AggregateOffer",
      "priceCurrency": "USD",
      "lowPrice": 79,
      "highPrice": 79,
      "offerCount": 3,
      "availability": "https://schema.org/InStock"
    },
    "hasVariant": [
      {
        "@type": "Product",
        "name": "XS",
        "sku": "NB-RMB-XS",
        "additionalProperty": [
          {
            "@type": "PropertyValue",
            "name": "Size",
            "value": "XS"
          }
        ],
        "offers": {
          "@type": "Offer",
          "priceCurrency": "USD",
          "price": 79,
          "availability": "https://schema.org/InStock",
          "url": "https://demo.aiptimise.com/products/ridge-merino-base-layer"
        }
      },
      {
        "@type": "Product",
        "name": "S",
        "sku": "NB-RMB-S",
        "additionalProperty": [
          {
            "@type": "PropertyValue",
            "name": "Size",
            "value": "S"
          }
        ],
        "offers": {
          "@type": "Offer",
          "priceCurrency": "USD",
          "price": 79,
          "availability": "https://schema.org/InStock",
          "url": "https://demo.aiptimise.com/products/ridge-merino-base-layer"
        }
      },
      {
        "@type": "Product",
        "name": "M",
        "sku": "NB-RMB-M",
        "additionalProperty": [
          {
            "@type": "PropertyValue",
            "name": "Size",
            "value": "M"
          }
        ],
        "offers": {
          "@type": "Offer",
          "priceCurrency": "USD",
          "price": 79,
          "availability": "https://schema.org/InStock",
          "url": "https://demo.aiptimise.com/products/ridge-merino-base-layer"
        }
      }
    ],
    "description": "A lightweight 150 gsm merino wool long-sleeve base layer that regulates temperature and resists odor on multi-day trips.",
    "disambiguatingDescription": "A 150 gsm merino wool base layer for cool-weather hiking that stays warm when damp and resists odor.",
    "additionalProperty": [
      {
        "@type": "PropertyValue",
        "name": "product_highlight",
        "value": "150 gsm merino wool"
      },
      {
        "@type": "PropertyValue",
        "name": "product_highlight",
        "value": "Flatlock seams"
      },
      {
        "@type": "PropertyValue",
        "name": "product_highlight",
        "value": "Odor resistant"
      },
      {
        "@type": "PropertyValue",
        "name": "product_highlight",
        "value": "Machine washable on wool cycle"
      }
    ],
    "dateModified": "2026-09-27T17:40:57.161Z",
    "image": "https://demo.aiptimise.com/images/ridge-merino-base-layer.jpg",
    "brand": {
      "@type": "Brand",
      "name": "Aiptimise Demo Store"
    },
    "category": "Apparel & Accessories > Clothing > Activewear",
    "url": "https://demo.aiptimise.com/products/ridge-merino-base-layer",
    "aggregateRating": {
      "@type": "AggregateRating",
      "ratingValue": 5,
      "reviewCount": 1,
      "bestRating": 5,
      "worstRating": 1
    },
    "subjectOf": {
      "@type": "FAQPage",
      "mainEntity": [
        {
          "@type": "Question",
          "name": "Is it machine washable?",
          "acceptedAnswer": {
            "@type": "Answer",
            "text": "Yes, on a cold wool cycle; lay flat to dry."
          }
        }
      ]
    },
    "breadcrumb": {
      "@type": "BreadcrumbList",
      "itemListElement": [
        {
          "@type": "ListItem",
          "position": 1,
          "name": "Apparel & Accessories"
        },
        {
          "@type": "ListItem",
          "position": 2,
          "name": "Clothing"
        },
        {
          "@type": "ListItem",
          "position": 3,
          "name": "Activewear"
        }
      ]
    }
  },
  "enriched_data": {
    "answer_engine_summary": "A 150 gsm merino wool base layer for cool-weather hiking that stays warm when damp and resists odor.",
    "product_highlights": [
      "150 gsm merino wool",
      "Flatlock seams",
      "Odor resistant",
      "Machine washable on wool cycle"
    ],
    "q_and_a": [
      {
        "q": "Is it machine washable?",
        "a": "Yes, on a cold wool cycle; lay flat to dry."
      }
    ],
    "optimized_title": "Ridge Merino Base Layer Top",
    "optimized_description": "A lightweight 150 gsm merino wool long-sleeve base layer that regulates temperature and resists odor on multi-day trips.",
    "use_cases": [
      {
        "scenario": "Layering for autumn hikes",
        "why": "Merino regulates temperature under a shell or fleece.",
        "rank": 1
      },
      {
        "scenario": "Travel with a light bag",
        "why": "Can be worn several days without washing.",
        "rank": 2
      }
    ],
    "reviews": [
      {
        "rating": 5,
        "body": "Soft, not itchy at all, wore it for a whole week-long trek.",
        "date": "2026-06-01T00:00:00.000Z"
      }
    ],
    "review_summary": {
      "review_count": 1,
      "average_rating": 5
    },
    "promotions": [],
    "policies": [
      {
        "type": "shipping",
        "summary": "Free standard shipping on US orders over $75; otherwise $6.95. Express $19.95.",
        "currency": "USD",
        "ships_to": [
          "US"
        ],
        "source_url": "https://demo.aiptimise.com/policies/shipping-policy",
        "free_shipping": true
      },
      {
        "type": "returns",
        "summary": "Free returns within 30 days of delivery for unused items.",
        "source_url": "https://demo.aiptimise.com/policies/refund-policy",
        "return_window_days": 30
      }
    ],
    "loyalty": {
      "name": "Trail Rewards",
      "tiers": [
        {
          "name": "Explorer",
          "perks": [
            "Birthday bonus of 50 points"
          ],
          "threshold_points": 0
        },
        {
          "name": "Summit",
          "perks": [
            "Free express shipping",
            "Early access to new gear"
          ],
          "threshold_points": 1000
        }
      ],
      "terms_url": "https://demo.aiptimise.com/pages/trail-rewards",
      "description": "Earn 1 point per dollar spent. Every 100 points is worth $5 off a future order."
    }
  },
  "variant_count": 3
}

get_product_variants#

Get product variantscatalog:readreadOnlyHint: truedestructiveHint: falseidempotentHint: trueopenWorldHint: false

Returns per-variant data (options, SKU, price, list price, availability) for one product of a participating merchant, with an aggregate offer summarising the price range. A product sold as a single variant returns an empty list; use get_live_price_and_inventory for its offer.

Parameters

Name	Type	Required	Description
`store_id`	string (UUID)	yes	Aiptimise public store ID (UUID)
`product_id`	string	yes	Product ID: the stable catalog item ID from a merchant feed, or the Aiptimise public product ID1–255 characters

Output fields (14)

Field	Type	Always present
`store_id`	string (UUID)	yes
`product_id`	string	yes
`variant_count`	integer	yes
`variants`	object[]	yes
`variants[].variant_id`	string	yes
`variants[].title`	string	yes
`variants[].sku`	string	no
`variants[].options`	map of string	yes
`variants[].price`	money	yes
`variants[].list_price`	money	no
`variants[].available`	boolean	no
`variants[].inventory_quantity`	number	no
`variants[].is_default`	boolean	no
`aggregate_offer`	object (free-form)	no

Example

Request (tools/call)

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_product_variants",
    "arguments": {
      "store_id": "edab46c9-76c6-4eb5-92dd-f593ed4bd9ad",
      "product_id": "demo-summit-rain-jacket"
    }
  }
}

Response: result.structuredContent

{
  "store_id": "edab46c9-76c6-4eb5-92dd-f593ed4bd9ad",
  "product_id": "demo-summit-rain-jacket",
  "variant_count": 4,
  "variants": [
    {
      "variant_id": "demo-summit-rain-jacket:demo-variant-1-1",
      "title": "S / Glacier Blue",
      "sku": "NB-SRJ-S-BLU",
      "options": {
        "Size": "S",
        "Color": "Glacier Blue"
      },
      "price": {
        "amount": "189.00",
        "currency": "USD"
      },
      "available": true,
      "is_default": true
    },
    {
      "variant_id": "demo-summit-rain-jacket:demo-variant-1-2",
      "title": "M / Glacier Blue",
      "sku": "NB-SRJ-M-BLU",
      "options": {
        "Size": "M",
        "Color": "Glacier Blue"
      },
      "price": {
        "amount": "189.00",
        "currency": "USD"
      },
      "available": true,
      "is_default": false
    },
    {
      "variant_id": "demo-summit-rain-jacket:demo-variant-1-3",
      "title": "L / Glacier Blue",
      "sku": "NB-SRJ-L-BLU",
      "options": {
        "Size": "L",
        "Color": "Glacier Blue"
      },
      "price": {
        "amount": "189.00",
        "currency": "USD"
      },
      "available": false,
      "is_default": false
    },
    {
      "variant_id": "demo-summit-rain-jacket:demo-variant-1-4",
      "title": "M / Basalt Black",
      "sku": "NB-SRJ-M-BLK",
      "options": {
        "Size": "M",
        "Color": "Basalt Black"
      },
      "price": {
        "amount": "189.00",
        "currency": "USD"
      },
      "available": true,
      "is_default": false
    }
  ],
  "aggregate_offer": {
    "@type": "AggregateOffer",
    "priceCurrency": "USD",
    "lowPrice": 189,
    "highPrice": 189,
    "offerCount": 4,
    "availability": "https://schema.org/InStock"
  }
}