{
  "openapi": "3.1.0",
  "info": {
    "title": "Sac City Auto Parts native Shopify API discovery",
    "version": "1.0.2",
    "description": "Read-only discovery, MCP tool listing and product recommendations exposed by this Shopify storefront. This document describes existing Shopify behavior; it does not create an API or change permissions. All documented operations are unauthenticated. Discover current tool schemas through tools/list before using other MCP methods. Cart, checkout, customer data and payment operations are outside this document. Native storefront HTML 404 pages are not JSON API responses."
  },
  "servers": [
    {
      "url": "https://saccityautoparts.com",
      "description": "Sac City Auto Parts storefront"
    }
  ],
  "security": [],
  "externalDocs": {
    "description": "Shopify agent integration documentation",
    "url": "https://shopify.dev/docs/agents"
  },
  "paths": {
    "/.well-known/ucp": {
      "get": {
        "operationId": "discoverCommerceCapabilities",
        "summary": "Discover native UCP services and capabilities",
        "description": "Use the current service endpoint and protocol version returned here. Shopify can advertise a canonical myshopify.com endpoint.",
        "security": [],
        "externalDocs": {
          "url": "https://shopify.dev/docs/agents"
        },
        "responses": {
          "200": {
            "description": "Discover native UCP services and capabilities",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UcpDiscovery"
                }
              }
            }
          }
        }
      }
    },
    "/.well-known/oauth-protected-resource": {
      "get": {
        "operationId": "discoverProtectedResource",
        "summary": "Read OAuth protected-resource metadata",
        "description": "RFC 9728 metadata published by Shopify. This store currently publishes resource, authorization_servers and bearer_methods_supported; scopes_supported is optional and currently absent. The authorization-server metadata separately declares supported scopes.",
        "security": [],
        "externalDocs": {
          "url": "https://www.rfc-editor.org/rfc/rfc9728.html"
        },
        "responses": {
          "200": {
            "description": "Read OAuth protected-resource metadata",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProtectedResourceMetadata"
                }
              }
            }
          }
        }
      }
    },
    "/.well-known/oauth-authorization-server": {
      "get": {
        "operationId": "discoverAuthorizationServer",
        "summary": "Read the store authorization server metadata",
        "description": "Shopify publishes customer authorization metadata here. The issuer, endpoints and supported scope names are authoritative. A scope being listed does not mean an arbitrary client has permission to obtain it.",
        "security": [],
        "externalDocs": {
          "url": "https://www.rfc-editor.org/rfc/rfc8414.html"
        },
        "responses": {
          "200": {
            "description": "Read the store authorization server metadata",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthorizationServerMetadata"
                }
              }
            }
          }
        }
      }
    },
    "/api/ucp/mcp": {
      "post": {
        "operationId": "listCommerceTools",
        "summary": "List the native UCP MCP tool schemas",
        "description": "Send the JSON-RPC tools/list method to inspect current tool input/output schemas. Listing succeeds without credentials. Only tool discovery is modeled here. Other tool calls can require a UCP agent profile, Shopify agent credentials, signatures or buyer authorization; follow the live schemas and Shopify documentation. The customer OAuth scheme below is not asserted to authorize UCP tool calls. JSON-RPC protocol errors can use HTTP 200: check for error as well as the HTTP status. For a complete MCP session, initialize first, send notifications/initialized, then send tools/list with the negotiated MCP-Protocol-Version and any returned Mcp-Session-Id. The bare tools/list example is an endpoint diagnostic supported by Shopify, not a substitute for MCP session initialization.",
        "security": [],
        "externalDocs": {
          "url": "https://shopify.dev/docs/agents/catalog/storefront-catalog"
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ToolsListRequest"
              },
              "example": {
                "jsonrpc": "2.0",
                "id": 1,
                "method": "tools/list"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Tool schemas, or a JSON-RPC protocol error.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/ToolsListResponse"
                    },
                    {
                      "$ref": "#/components/schemas/JsonRpcErrorResponse"
                    }
                  ]
                },
                "examples": {
                  "methodNotFound": {
                    "summary": "Observed response to an unknown method; use tools/list and its advertised tools.",
                    "value": {
                      "jsonrpc": "2.0",
                      "id": 2,
                      "error": {
                        "code": -32601,
                        "message": "Method not found",
                        "data": "__ora_readiness_nonexistent_method"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/recommendations/products.json": {
      "get": {
        "operationId": "getProductRecommendations",
        "summary": "Get related or complementary storefront products",
        "description": "Read-only Shopify Ajax Product Recommendations API in the store default locale. Use a currently published product ID. The response may contain no products. Shopify also supports locale-aware URLs; this document describes the verified default-locale route.",
        "security": [],
        "externalDocs": {
          "url": "https://shopify.dev/docs/api/ajax/reference/product-recommendations"
        },
        "parameters": [
          {
            "name": "product_id",
            "in": "query",
            "required": true,
            "description": "ID of an existing product published in the Online Store.",
            "schema": {
              "type": "integer",
              "format": "int64",
              "minimum": 1
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Maximum number of recommendations.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 10,
              "default": 10
            }
          },
          {
            "name": "intent",
            "in": "query",
            "required": false,
            "description": "Recommendation strategy.",
            "schema": {
              "type": "string",
              "enum": [
                "related",
                "complementary"
              ],
              "default": "related"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Product recommendations; an empty products array is a valid result.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProductRecommendations"
                }
              }
            }
          },
          "404": {
            "description": "The product is not published or does not exist. Resolve a currently published product ID and retry.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AjaxError"
                },
                "example": {
                  "status": 404,
                  "message": "Product not found",
                  "description": "No product with id 0 is published in the online store"
                }
              }
            }
          },
          "422": {
            "description": "A required parameter is missing or a parameter is invalid. Supply product_id for a published product, limit from 1 to 10, and intent related or complementary, then retry.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AjaxError"
                },
                "example": {
                  "status": 422,
                  "message": "Missing parameter error",
                  "description": "A product_id value is missing"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ShopifyCustomerOAuth": {
        "type": "oauth2",
        "description": "Scopes advertised by this store’s Shopify customer authorization server. This declaration is informational for future authenticated integrations; none is required by the public operations in this document. Request only the scope needed for the selected integration, and follow Shopify client registration, consent and PKCE requirements. Listed scopes do not grant access or establish support for all clients. UCP agent authentication can use a different Shopify token service; see https://shopify.dev/docs/agents/get-started/authentication.",
        "flows": {
          "authorizationCode": {
            "authorizationUrl": "https://shopify.com/authentication/59377975384/oauth/authorize",
            "tokenUrl": "https://shopify.com/authentication/59377975384/oauth/token",
            "scopes": {
              "openid": "OpenID Connect identity scope, advertised by the authorization server.",
              "email": "Email identity scope, advertised by the authorization server.",
              "customer-account-api:full": "Full customer account API scope advertised by the authorization server; request only for an authorized customer account integration.",
              "customer-account-mcp-api:full": "Full customer account MCP scope advertised by the authorization server; request only for an authorized customer account MCP integration.",
              "dev.ucp.shopping.checkout:manage": "UCP checkout management scope advertised by the authorization server; not required for public discovery or product recommendations.",
              "dev.ucp.shopping.catalog.search:read": "UCP catalog search read scope advertised by the authorization server; not required for public discovery or product recommendations."
            }
          }
        }
      }
    },
    "schemas": {
      "UcpDiscovery": {
        "type": "object",
        "required": [
          "ucp"
        ],
        "properties": {
          "ucp": {
            "type": "object",
            "required": [
              "version",
              "services",
              "capabilities"
            ],
            "properties": {
              "version": {
                "type": "string"
              },
              "services": {
                "type": "object"
              },
              "capabilities": {
                "type": "object"
              }
            },
            "additionalProperties": true
          }
        },
        "additionalProperties": true
      },
      "ProtectedResourceMetadata": {
        "type": "object",
        "required": [
          "resource"
        ],
        "properties": {
          "resource": {
            "type": "string",
            "format": "uri"
          },
          "authorization_servers": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "uri"
            }
          },
          "bearer_methods_supported": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "scopes_supported": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "additionalProperties": true
      },
      "AuthorizationServerMetadata": {
        "type": "object",
        "required": [
          "issuer"
        ],
        "properties": {
          "issuer": {
            "type": "string",
            "format": "uri"
          },
          "authorization_endpoint": {
            "type": "string",
            "format": "uri"
          },
          "token_endpoint": {
            "type": "string",
            "format": "uri"
          },
          "scopes_supported": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "grant_types_supported": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "code_challenge_methods_supported": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "additionalProperties": true
      },
      "ToolsListRequest": {
        "type": "object",
        "required": [
          "jsonrpc",
          "id",
          "method"
        ],
        "properties": {
          "jsonrpc": {
            "const": "2.0",
            "type": "string"
          },
          "id": {
            "type": [
              "string",
              "integer"
            ]
          },
          "method": {
            "const": "tools/list",
            "type": "string"
          },
          "params": {
            "type": "object",
            "properties": {
              "cursor": {
                "type": "string"
              }
            },
            "additionalProperties": true
          }
        },
        "additionalProperties": false
      },
      "ToolsListResponse": {
        "type": "object",
        "required": [
          "jsonrpc",
          "id",
          "result"
        ],
        "properties": {
          "jsonrpc": {
            "const": "2.0",
            "type": "string"
          },
          "id": {
            "type": [
              "string",
              "integer"
            ]
          },
          "result": {
            "type": "object",
            "required": [
              "tools"
            ],
            "properties": {
              "tools": {
                "type": "array",
                "items": {
                  "type": "object",
                  "required": [
                    "name",
                    "inputSchema"
                  ],
                  "properties": {
                    "name": {
                      "type": "string"
                    },
                    "description": {
                      "type": "string"
                    },
                    "inputSchema": {
                      "type": "object"
                    },
                    "outputSchema": {
                      "type": "object"
                    }
                  },
                  "additionalProperties": true
                }
              },
              "nextCursor": {
                "type": "string"
              }
            },
            "additionalProperties": true
          }
        },
        "not": {
          "required": [
            "error"
          ]
        },
        "additionalProperties": true
      },
      "JsonRpcErrorResponse": {
        "type": "object",
        "required": [
          "jsonrpc",
          "id",
          "error"
        ],
        "properties": {
          "jsonrpc": {
            "const": "2.0",
            "type": "string"
          },
          "id": {
            "type": [
              "string",
              "integer",
              "null"
            ]
          },
          "error": {
            "type": "object",
            "required": [
              "code",
              "message"
            ],
            "properties": {
              "code": {
                "type": "integer"
              },
              "message": {
                "type": "string"
              },
              "data": {
                "description": "Native JSON-RPC error details. May be text or a structured value; it is not an RFC 9457 problem document."
              }
            },
            "additionalProperties": true
          }
        },
        "not": {
          "required": [
            "result"
          ]
        },
        "additionalProperties": true
      },
      "ProductRecommendations": {
        "type": "object",
        "required": [
          "products"
        ],
        "properties": {
          "products": {
            "type": "array",
            "maxItems": 10,
            "items": {
              "type": "object",
              "required": [
                "id",
                "title",
                "handle",
                "url"
              ],
              "properties": {
                "id": {
                  "type": "integer",
                  "format": "int64"
                },
                "title": {
                  "type": "string"
                },
                "handle": {
                  "type": "string"
                },
                "url": {
                  "type": "string",
                  "description": "Storefront product URL, which may be relative and include recommendation query parameters."
                }
              },
              "additionalProperties": true
            }
          },
          "intent": {
            "type": "string",
            "enum": [
              "related",
              "complementary"
            ]
          }
        },
        "additionalProperties": true
      },
      "AjaxError": {
        "type": "object",
        "required": [
          "status",
          "message",
          "description"
        ],
        "properties": {
          "status": {
            "type": "integer",
            "description": "Native Shopify HTTP error status code."
          },
          "message": {
            "type": "string",
            "minLength": 1
          },
          "description": {
            "type": "string",
            "minLength": 1,
            "description": "Native explanation identifying the missing or invalid input. Recovery guidance in this OpenAPI document is documentation, not an added response field."
          }
        },
        "additionalProperties": true
      }
    }
  }
}