Retrieve a single product by ID, including its prices, variants, stock, tax and file settings. Product IDs come from a page response (data.product.id on get_checkout_page). Read-only.
| Name | Required | Description | Default |
|---|---|---|---|
| productId | Yes | The ID of the product to retrieve. Find it on a page response as `data.product.id` (see `get_checkout_page`). |
| Name | Required | Description | Default |
|---|---|---|---|
| data | Yes |
Changes observed during successful MCP inspections.
Output schema / properties / data / properties / prices / anyOfPrevious value: -[
- {
- "items": {
- "additionalProperties": false,
- "description": "A single price entry on a multi-price product.",
- "properties": {
- "amount": {
- "description": "Price in smallest currency unit (cents).",
- "example": 4900,
- "type": "number"
- },
- "badge": {
- "description": "Optional short label shown over the price card.",
- "type": [
- "string",
- "null"
- ]
- },
- "badgeIcon": {
- "anyOf": [
- {
- "description": "Icon shown before the badge text.",
- "enum": [
- "star",
- "sparkles",
- "fire",
- "bolt",
- "rocket",
- "trophy",
- "check",
- "x-mark",
- "plus",
- "arrow-right",
- "check-badge",
- "check-circle",
- "shield-check",
- "thumbs-up",
- "heart",
- "smile",
- "light-bulb",
- "sun",
- "moon",
- "gift",
- "tag",
- "percent",
- "dollar",
- "banknotes",
- "credit-card",
- "shopping-bag",
- "shopping-cart",
- "truck",
- "clock",
- "calendar",
- "bell",
- "megaphone",
- "trending-up",
- "chart",
- "refresh",
- "lock",
- "key",
- "ticket",
- "users",
- "academic-cap",
- "book",
- "music",
- "video",
- "document",
- "download",
- "mobile",
- "camera",
- "paint-brush",
- "puzzle",
- "cube",
- "globe",
- "map-pin",
- "storefront",
- "tools",
- "beaker",
- "lifebuoy",
- "chat",
- "envelope",
- "phone",
- "cake",
- "scale",
- "eye"
- ],
- "example": "star",
- "type": "string"
- },
- {
- "type": "null"
- }
- ],
- "description": "Optional icon shown before the badge text."
- },
- "billingType": {
- "description": "Billing type. Immutable once the price exists (see the pricing-type identity lock).",
- "enum": [
- "one_time",
- "recurring"
- ],
- "example": "one_time",
- "type": "string"
- },
- "currency": {
- "description": "Lowercase ISO 4217 currency code.",
- "example": "usd",
- "type": "string"
- },
- "discountedFromPrice": {
- "description": "Original price before discount, in cents.",
- "type": [
- "number",
- "null"
- ]
- },
- "enabled": {
- "description": "Whether this price is selectable by customers.",
- "type": "boolean"
- },
- "hidden": {
- "description": "Hide this price. Hidden prices can still be shown using query parameters.",
- "type": [
- "boolean",
- "null"
- ]
- },
- "id": {
- "description": "Unique price identifier.",
- "example": "507f1f77bcf86cd799439011",
- "type": "string"
- },
- "isDefault": {
- "description": "Whether checkout pre-selects this price: the entry `defaultPriceId` names. False on every price when the product has several prices and no default.",
- "type": "boolean"
- },
- "label": {
- "description": "Optional seller-facing label (e.g. \"Monthly\", \"Annual\").",
- "type": [
- "string",
- "null"
- ]
- },
- "order": {
- "description": "Dashboard display order.",
- "type": [
- "number",
- "null"
- ]
- },
- "payWhatYouWant": {
- "description": "Whether pay-what-you-want pricing is enabled.",
- "type": [
- "boolean",
- "null"
- ]
- },
- "paymentPlan": {
- "anyOf": [
- {
- "additionalProperties": false,
- "properties": {
- "billingCycleAnchorConfig": {
- "anyOf": [
- {
- "additionalProperties": false,
- "properties": {
- "dayOfMonth": {
- "anyOf": [
- {
- "maximum": 31,
- "minimum": 1,
- "type": "number"
- },
- {
- "type": "null"
- }
- ],
- "description": "Day of month the billing cycle is anchored to."
- },
- "enabled": {
- "type": [
- "boolean",
- "null"
- ]
- },
- "month": {
- "anyOf": [
- {
- "maximum": 12,
- "minimum": 1,
- "type": "number"
- },
- {
- "type": "null"
- }
- ]
- }
- },
- "type": "object"
- },
- {
- "type": "null"
- }
- ]
- },
- "interval": {
- "anyOf": [
- {
- "enum": [
- "day",
- "week",
- "month",
- "year"
- ],
- "type": "string"
- },
- {
- "type": "null"
- }
- ],
- "description": "Billing interval (day, week, month, year).",
- "example": "month"
- },
- "intervalCount": {
- "description": "Number of intervals between billings.",
- "example": 1,
- "type": [
- "number",
- "null"
- ]
- },
- "planIterations": {
- "description": "Number of billing cycles after which the plan completes.",
- "type": [
- "number",
- "null"
- ]
- },
- "startDate": {
- "anyOf": [
- {
- "format": "date-time",
- "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$",
- "type": "string"
- },
- {
- "type": "null"
- }
- ],
- "description": "The date on which the subscription begins."
- },
- "trialPeriodDays": {
- "description": "Trial period in days.",
- "type": [
- "number",
- "null"
- ]
- }
- },
- "type": "object"
- },
- {
- "type": "null"
- }
- ],
- "description": "Payment plan configuration — recurring billing that completes after `planIterations` cycles. Never present together with recurring."
- },
- "pwywSuggestedPrice": {
- "description": "Suggested price in cents for PWYW prices.",
- "type": [
- "number",
- "null"
- ]
- },
- "recurring": {
- "anyOf": [
- {
- "additionalProperties": false,
- "properties": {
- "billingCycleAnchorConfig": {
- "anyOf": [
- {
- "additionalProperties": false,
- "properties": {
- "dayOfMonth": {
- "anyOf": [
- {
- "maximum": 31,
- "minimum": 1,
- "type": "number"
- },
- {
- "type": "null"
- }
- ],
- "description": "Day of month the billing cycle is anchored to."
- },
- "enabled": {
- "type": [
- "boolean",
- "null"
- ]
- },
- "month": {
- "anyOf": [
- {
- "maximum": 12,
- "minimum": 1,
- "type": "number"
- },
- {
- "type": "null"
- }
- ]
- }
- },
- "type": "object"
- },
- {
- "type": "null"
- }
- ]
- },
- "interval": {
- "anyOf": [
- {
- "enum": [
- "day",
- "week",
- "month",
- "year"
- ],
- "type": "string"
- },
- {
- "type": "null"
- }
- ],
- "description": "Billing interval (day, week, month, year).",
- "example": "month"
- },
- "intervalCount": {
- "description": "Number of intervals between billings.",
- "example": 1,
- "type": [
- "number",
- "null"
- ]
- },
- "startDate": {
- "anyOf": [
- {
- "format": "date-time",
- "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$",
- "type": "string"
- },
- {
- "type": "null"
- }
- ],
- "description": "The date on which the subscription begins."
- },
- "trialPeriodDays": {
- "description": "Trial period in days.",
- "type": [
- "number",
- "null"
- ]
- }
- },
- "type": "object"
- },
- {
- "type": "null"
- }
- ],
- "description": "Recurring billing configuration. Never present together with paymentPlan."
- },
- "reference": {
- "description": "Merchant-facing internal id used in exports and reports (e.g. `price_one_time_fixed_5000`).",
- "type": [
- "string",
- "null"
- ]
- },
- "setupFee": {
- "description": "One-time setup fee in cents.",
- "type": [
- "number",
- "null"
- ]
- },
- "setupFeeMultipliesWithQuantity": {
- "type": [
- "boolean",
- "null"
- ]
- }
- },
- "required": [
- "amount",
- "currency",
- "id",
- "enabled",
- "isDefault",
- "billingType"
- ],
- "type": "object"
- },
- "type": "array"
- },
- {
- "type": "null"
- }
-]New value: +[
+ {
+ "items": {
+ "additionalProperties": false,
+ "description": "A single price entry on a multi-price product.",
+ "properties": {
+ "amount": {
+ "description": "Price in smallest currency unit (cents).",
+ "example": 4900,
+ "type": "number"
+ },
+ "badge": {
+ "description": "Optional short label shown over the price card.",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "badgeIcon": {
+ "anyOf": [
+ {
+ "description": "Icon shown before the badge text.",
+ "enum": [
+ "star",
+ "sparkles",
+ "fire",
+ "bolt",
+ "rocket",
+ "trophy",
+ "check",
+ "x-mark",
+ "plus",
+ "arrow-right",
+ "check-badge",
+ "check-circle",
+ "shield-check",
+ "thumbs-up",
+ "heart",
+ "smile",
+ "light-bulb",
+ "sun",
+ "moon",
+ "gift",
+ "tag",
+ "percent",
+ "dollar",
+ "banknotes",
+ "credit-card",
+ "shopping-bag",
+ "shopping-cart",
+ "truck",
+ "clock",
+ "calendar",
+ "bell",
+ "megaphone",
+ "trending-up",
+ "chart",
+ "refresh",
+ "lock",
+ "key",
+ "ticket",
+ "users",
+ "academic-cap",
+ "book",
+ "music",
+ "video",
+ "document",
+ "download",
+ "mobile",
+ "camera",
+ "paint-brush",
+ "puzzle",
+ "cube",
+ "globe",
+ "map-pin",
+ "storefront",
+ "tools",
+ "beaker",
+ "lifebuoy",
+ "chat",
+ "envelope",
+ "phone",
+ "cake",
+ "scale",
+ "eye"
+ ],
+ "example": "star",
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "Optional icon shown before the badge text."
+ },
+ "billingType": {
+ "description": "Billing type. Immutable once the price exists (see the pricing-type identity lock).",
+ "enum": [
+ "one_time",
+ "recurring"
+ ],
+ "example": "one_time",
+ "type": "string"
+ },
+ "currency": {
+ "description": "Lowercase ISO 4217 currency code.",
+ "example": "usd",
+ "type": "string"
+ },
+ "discountedFromPrice": {
+ "description": "Original price before discount, in cents.",
+ "type": [
+ "number",
+ "null"
+ ]
+ },
+ "enabled": {
+ "description": "Whether this price is selectable by customers.",
+ "type": "boolean"
+ },
+ "hidden": {
+ "description": "Hide this price. Hidden prices can still be shown using query parameters.",
+ "type": [
+ "boolean",
+ "null"
+ ]
+ },
+ "id": {
+ "description": "Unique price identifier.",
+ "example": "507f1f77bcf86cd799439011",
+ "type": "string"
+ },
+ "isDefault": {
+ "description": "Whether checkout pre-selects this price: the entry `defaultPriceId` names. False on every price when the product has several prices and no default.",
+ "type": "boolean"
+ },
+ "label": {
+ "description": "Optional seller-facing label (e.g. \"Monthly\", \"Annual\").",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "order": {
+ "description": "Dashboard display order.",
+ "type": [
+ "number",
+ "null"
+ ]
+ },
+ "payWhatYouWant": {
+ "description": "Whether pay-what-you-want pricing is enabled.",
+ "type": [
+ "boolean",
+ "null"
+ ]
+ },
+ "paymentPlan": {
+ "anyOf": [
+ {
+ "additionalProperties": false,
+ "properties": {
+ "billingCycleAnchorConfig": {
+ "anyOf": [
+ {
+ "additionalProperties": false,
+ "properties": {
+ "dayOfMonth": {
+ "anyOf": [
+ {
+ "maximum": 31,
+ "minimum": 1,
+ "type": "number"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "Day of month the billing cycle is anchored to."
+ },
+ "enabled": {
+ "type": [
+ "boolean",
+ "null"
+ ]
+ },
+ "month": {
+ "anyOf": [
+ {
+ "maximum": 12,
+ "minimum": 1,
+ "type": "number"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ }
+ },
+ "type": "object"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "interval": {
+ "anyOf": [
+ {
+ "enum": [
+ "day",
+ "week",
+ "month",
+ "year"
+ ],
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "Billing interval (day, week, month, year).",
+ "example": "month"
+ },
+ "intervalCount": {
+ "description": "Number of intervals between billings.",
+ "example": 1,
+ "type": [
+ "number",
+ "null"
+ ]
+ },
+ "planIterations": {
+ "description": "Number of billing cycles after which the plan completes.",
+ "type": [
+ "number",
+ "null"
+ ]
+ },
+ "startDate": {
+ "anyOf": [
+ {
+ "format": "date-time",
+ "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$",
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "The date on which the subscription begins."
+ },
+ "trialPeriodDays": {
+ "description": "Trial period in days.",
+ "type": [
+ "number",
+ "null"
+ ]
+ }
+ },
+ "type": "object"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "Payment plan configuration — recurring billing that completes after `planIterations` cycles. Never present together with recurring."
+ },
+ "pwywSuggestedPrice": {
+ "description": "Suggested price in cents for PWYW prices.",
+ "type": [
+ "number",
+ "null"
+ ]
+ },
+ "recurring": {
+ "anyOf": [
+ {
+ "additionalProperties": false,
+ "properties": {
+ "billingCycleAnchorConfig": {
+ "anyOf": [
+ {
+ "additionalProperties": false,
+ "properties": {
+ "dayOfMonth": {
+ "anyOf": [
+ {
+ "maximum": 31,
+ "minimum": 1,
+ "type": "number"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "Day of month the billing cycle is anchored to."
+ },
+ "enabled": {
+ "type": [
+ "boolean",
+ "null"
+ ]
+ },
+ "month": {
+ "anyOf": [
+ {
+ "maximum": 12,
+ "minimum": 1,
+ "type": "number"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ }
+ },
+ "type": "object"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "interval": {
+ "anyOf": [
+ {
+ "enum": [
+ "day",
+ "week",
+ "month",
+ "year"
+ ],
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "Billing interval (day, week, month, year).",
+ "example": "month"
+ },
+ "intervalCount": {
+ "description": "Number of intervals between billings.",
+ "example": 1,
+ "type": [
+ "number",
+ "null"
+ ]
+ },
+ "startDate": {
+ "anyOf": [
+ {
+ "format": "date-time",
+ "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$",
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "The date on which the subscription begins."
+ },
+ "trialPeriodDays": {
+ "description": "Trial period in days.",
+ "type": [
+ "number",
+ "null"
+ ]
+ }
+ },
+ "type": "object"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "Recurring billing configuration. Never present together with paymentPlan."
+ },
+ "reference": {
+ "description": "Stable label for this price, sent to exports, Zapier, Google Sheets and webhooks as `priceReference`. A generated reference can contain the amount the price was created with, such as `price_one_time_fixed_5000`. It is not updated when the amount changes, and does not need to be.",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "setupFee": {
+ "description": "One-time setup fee in cents.",
+ "type": [
+ "number",
+ "null"
+ ]
+ },
+ "setupFeeMultipliesWithQuantity": {
+ "type": [
+ "boolean",
+ "null"
+ ]
+ }
+ },
+ "required": [
+ "amount",
+ "currency",
+ "id",
+ "enabled",
+ "isDefault",
+ "billingType"
+ ],
+ "type": "object"
+ },
+ "type": "array"
+ },
+ {
+ "type": "null"
+ }
+]Output schema / properties / data / properties / role / anyOfPrevious value: -[
- {
- "description": "What the product is for. `orderbump` products are the simplified add-ons a checkout page offers as order bumps and an event page offers as add-ons; they can never be sold as a page product, and a product cannot be converted between roles. `orderbump` products are only available for beta testing of the order bump feature.",
- "enum": [
- "product",
- "orderbump"
- ],
- "example": "product",
- "type": "string"
- },
- {
- "type": "null"
- }
-]New value: +[
+ {
+ "description": "What the product is for. `orderbump` products are the simplified add-ons a checkout page offers as order bumps and an event page offers as add-ons; they can never be sold as a page product, and a product cannot be converted between roles.",
+ "enum": [
+ "product",
+ "orderbump"
+ ],
+ "example": "product",
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+]Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds useful behavioral context by enumerating the product data included and clarifying the ID provenance, though it does not describe not-found behavior or auth requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with no waste: the retrieval scope and returned fields come first, followed by the ID provenance note. It is appropriately sized and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-resource read tool with full schema coverage, clear annotations, and an output schema, the description provides everything needed to understand scope and invocation. Return-value details are rightly left to the output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the single productId parameter is fully documented in the schema with its pattern and source. The description reinforces the ID source but does not add format or semantic details beyond what the schema already provides, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: "Retrieve a single product by ID," and lists the data returned (prices, variants, stock, tax, file settings). This clearly distinguishes it from siblings like list_products and update_product without needing the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool by saying it retrieves a single product by ID, and it explains where to find that ID via get_checkout_page. However, it does not explicitly compare against alternatives such as list_products or state when not to use it, leaving guidance at an implied level.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add one secure layer between your agents and this server.