{ "openapi": "3.1.0", "info": { "title": "BHPB Storefront & Agent API", "description": "Official machine-readable API for BHPB e-commerce store (baggy snowboard pants and outerwear). Designed for autonomous shopping agents, catalog aggregators, and developer integrations.", "version": "1.0.0", "termsOfService": "https://bhpb.shop/policies/terms-of-service", "contact": { "name": "BHPB Developer Support", "email": "kontakt@bhpb.shop", "url": "https://bhpb.shop/developers" }, "license": { "name": "Proprietary", "url": "https://bhpb.shop/policies/terms-of-service" } }, "servers": [ { "url": "https://bhpb.shop", "description": "Production Storefront" }, { "url": "https://mock.shop", "description": "Free Public Sandbox Environment (Mock API)" } ], "security": [ { "PublicRead": [] }, { "OAuth2": [ "products:read" ] } ], "paths": { "/products.json": { "get": { "operationId": "listProducts", "summary": "List all published products", "description": "Returns a paginated list of snowboard pants and gear with pricing, images, descriptions, and variant stock availability.", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Number of products per page (1-250, default: 30)", "schema": { "type": "integer", "default": 30, "minimum": 1, "maximum": 250 } }, { "name": "page", "in": "query", "required": false, "description": "Page index (1-based)", "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "collection_id", "in": "query", "required": false, "description": "Filter by Shopify collection ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful retrieval of product catalog", "content": { "application/json": { "schema": { "type": "object", "required": [ "products" ], "properties": { "products": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } } } } } } }, "400": { "description": "Invalid query parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/products/{handle}.json": { "get": { "operationId": "getProductByHandle", "summary": "Retrieve single product details", "description": "Fetches complete technical specifications, waterproofing (10K-15K), available colorways, sizing options, and variant prices for a given handle.", "parameters": [ { "name": "handle", "in": "path", "required": true, "description": "Product handle slug (e.g. 'illuminati', 'gsou-snow', 'pinky', 'orbit')", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Product found", "content": { "application/json": { "schema": { "type": "object", "required": [ "product" ], "properties": { "product": { "$ref": "#/components/schemas/Product" } } } } } }, "404": { "description": "Product not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/collections.json": { "get": { "operationId": "listCollections", "summary": "List collections", "description": "Returns all public collections in the BHPB catalog.", "responses": { "200": { "description": "List of collections", "content": { "application/json": { "schema": { "type": "object", "required": [ "collections" ], "properties": { "collections": { "type": "array", "items": { "$ref": "#/components/schemas/Collection" } } } } } } } } } }, "/collections/{handle}/products.json": { "get": { "operationId": "getCollectionProducts", "summary": "List products in collection", "description": "Returns products belonging to the specified collection handle.", "parameters": [ { "name": "handle", "in": "path", "required": true, "description": "Collection handle (e.g. 'wszystkie-spodnie', 'gsou-snow', 'bhpb')", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Collection products found", "content": { "application/json": { "schema": { "type": "object", "required": [ "products" ], "properties": { "products": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } } } } } } }, "404": { "description": "Collection not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } } }, "components": { "securitySchemes": { "PublicRead": { "type": "apiKey", "name": "none", "in": "header", "description": "Public catalog endpoints (/products.json, /collections.json) are accessible without authentication." }, "OAuth2": { "type": "oauth2", "description": "OAuth 2.0 machine-readable scopes for agent-authenticated operations.", "flows": { "clientCredentials": { "tokenUrl": "https://fc3v0y-0r.myshopify.com/admin/oauth/access_token", "scopes": { "products:read": "Read-only access to published products, variants, and pricing.", "cart:write": "Create and manage customer carts and prepare checkout sessions." } } } }, "StorefrontToken": { "type": "apiKey", "name": "X-Shopify-Storefront-Access-Token", "in": "header", "description": "Storefront API access token for headless storefronts and agents." } }, "schemas": { "Product": { "type": "object", "required": [ "id", "title", "handle", "variants", "images" ], "properties": { "id": { "type": "integer", "format": "int64", "example": 16215010410874 }, "title": { "type": "string", "example": "Illuminati" }, "handle": { "type": "string", "example": "illuminati" }, "body_html": { "type": "string", "example": "

BHPB flagship pants featuring an uncompromising balloon baggy fit...

" }, "vendor": { "type": "string", "example": "BHPB" }, "product_type": { "type": "string", "example": "Snowboard pants" }, "published_at": { "type": "string", "format": "date-time" }, "tags": { "type": "array", "items": { "type": "string" }, "example": [ "illuminati", "baggy" ] }, "variants": { "type": "array", "items": { "$ref": "#/components/schemas/Variant" } }, "images": { "type": "array", "items": { "$ref": "#/components/schemas/ProductImage" } }, "options": { "type": "array", "items": { "$ref": "#/components/schemas/ProductOption" } } } }, "Variant": { "type": "object", "required": [ "id", "title", "price", "available" ], "properties": { "id": { "type": "integer", "format": "int64", "example": 57316612538746 }, "title": { "type": "string", "example": "Black / M (150–160 cm)" }, "option1": { "type": "string", "example": "Black" }, "option2": { "type": "string", "example": "M (150–160 cm)" }, "option3": { "type": "string", "nullable": true }, "sku": { "type": "string", "nullable": true, "example": "BHPB-ILL-BLK-M" }, "requires_shipping": { "type": "boolean", "example": true }, "taxable": { "type": "boolean", "example": true }, "available": { "type": "boolean", "example": true }, "price": { "type": "string", "example": "399.00" }, "grams": { "type": "integer", "example": 1300 }, "compare_at_price": { "type": "string", "nullable": true } } }, "ProductImage": { "type": "object", "required": [ "id", "src" ], "properties": { "id": { "type": "integer", "format": "int64" }, "src": { "type": "string", "format": "uri" }, "width": { "type": "integer" }, "height": { "type": "integer" }, "alt": { "type": "string", "nullable": true } } }, "ProductOption": { "type": "object", "required": [ "name", "position", "values" ], "properties": { "name": { "type": "string", "example": "Colour" }, "position": { "type": "integer", "example": 1 }, "values": { "type": "array", "items": { "type": "string" }, "example": [ "Black", "Graphite", "Cream" ] } } }, "Collection": { "type": "object", "required": [ "id", "handle", "title" ], "properties": { "id": { "type": "integer", "format": "int64", "example": 326798835962 }, "handle": { "type": "string", "example": "wszystkie-spodnie" }, "title": { "type": "string", "example": "All pants" }, "body_html": { "type": "string", "nullable": true }, "products_count": { "type": "integer", "example": 5 } } }, "ErrorResponse": { "type": "object", "required": [ "code", "message", "resolution_hint" ], "properties": { "code": { "type": "string", "example": "not_found", "description": "Machine-readable error identifier." }, "message": { "type": "string", "example": "The requested resource could not be found.", "description": "Human-readable explanation of the error." }, "resolution_hint": { "type": "string", "example": "Verify the resource identifier at https://bhpb.shop/products.json or consult https://bhpb.shop/docs", "description": "Actionable guidance for autonomous agents to recover from the error." } } } } } }