

ECO SHADES API
The ECO SHADES API gives developers and AI agents programmatic access to the ECO SHADES online store: the product catalog, search, the Storefront GraphQL API and the store's Model Context Protocol (MCP) servers for carts and checkout. No API key is needed.
Quick links
- OpenAPI 3.1 specification: https://www.eco-shades.com/openapi.json
- ECO SHADES MCP server: https://www.eco-shades.com/pages/mcp
- Agent instructions: https://www.eco-shades.com/agents.md
- UCP profile: https://www.eco-shades.com/.well-known/ucp
- npm package: eco-shades-mcp
Base URL and authentication
Base URL: https://www.eco-shades.com. All endpoints below are public and read-only, except the MCP cart and checkout tools. No API key or OAuth token is needed. Identify agent traffic as described in agents.md.
Endpoints
| Operation | Method and path | What it returns |
|---|---|---|
| listProducts | GET /products.json?limit=250&page=1 |
Published products with variants, SKUs, images and options. Page until the array is empty. |
| getProduct | GET /products/{handle}.json |
One product by handle. |
| getProductPrices | GET /products/{handle}.js |
One product with live availability per variant and prices in minor units. |
| listCollections | GET /collections.json |
Published collections. |
| listCollectionProducts | GET /collections/{handle}/products.json |
Products in one collection (all = every product). |
| searchStore | GET /search/suggest.json?q=black&resources[type]=product |
Matching products, collections, articles and pages. |
| queryStorefrontGraphql | POST /api/2026-10/graphql.json |
Shopify Storefront GraphQL, tokenless. Query cost is in extensions.cost. |
| getUcpProfile | GET /.well-known/ucp |
Universal Commerce Protocol profile: capabilities and the MCP endpoint. |
| callCommerceMcp | POST /api/ucp/mcp |
MCP server for catalog search, carts, checkout and orders. |
| callStoreMcp | POST /api/mcp |
MCP server for store policies and FAQs. |
Example requests
curl "https://www.eco-shades.com/products.json?limit=5"
curl "https://www.eco-shades.com/search/suggest.json?q=black&resources[type]=product"
curl -X POST "https://www.eco-shades.com/api/2026-10/graphql.json" \
-H "Content-Type: application/json" \
-d '{"query":"{ products(first: 5) { nodes { handle title availableForSale } } }"}'
curl -X POST "https://www.eco-shades.com/api/ucp/mcp" \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
Carts, checkout and buyer approval
Use the MCP server at /api/ucp/mcp for carts and checkout. Do not script the browser cart or checkout forms. Orders may only be placed with the buyer's explicit approval; follow the review and handoff steps the tools return. See the ECO SHADES MCP server page.
Prices, errors and rate limits
- REST
.jsonendpoints return prices as decimal strings in the store's default currency..jsand MCP responses use integers in minor units. Always use the price the API returns. - Unknown products return HTTP 404. GraphQL and MCP errors come back in the response body (
errorsor JSON-RPCerror). - On HTTP 429, wait for
Retry-After(if present) and retry with exponential backoff.
Store policies
Shipping · Returns · Terms · Privacy · Contact us

