{"openapi":"3.1.0","info":{"title":"Snappy Agents API","version":"1.0.0","description":"Marketplace API for AI agents. Lets a signed-in user search the Snappy Marketplace, get a live landed price for a country, pay through a hosted Stripe Checkout link, and receive real-time order confirmation, receipts and tracking.\n\n**Tool classification (Meta Muse):** every operation is tagged `x-tool-class` = `read`, `write` or `sensitive-write`. Sensitive writes (creating a checkout, cancelling an order) must always prompt the user.\n\nAuthentication: OAuth 2.1 (authorization code + PKCE). Discovery at `/.well-known/oauth-authorization-server` and `/.well-known/oauth-protected-resource`.","contact":{"name":"Snappy","url":"https://www.snappy.com","email":"support@snappy.com"},"termsOfService":"https://www.snappy.com/terms"},"components":{"securitySchemes":{"oauth2":{"type":"oauth2","flows":{"authorizationCode":{"authorizationUrl":"https://agents.snappy.com/oauth/authorize","tokenUrl":"https://agents.snappy.com/oauth/token","refreshUrl":"https://agents.snappy.com/oauth/token","scopes":{"profile":"Profile","catalog:read":"Browse the marketplace","orders:read":"Read orders","orders:write":"Create checkouts and cancel orders","offline_access":"Refresh tokens"}}}}},"schemas":{}},"paths":{"/.well-known/oauth-authorization-server":{"get":{"operationId":"getAuthorizationServerMetadata","summary":"OAuth 2.1 authorization server metadata (RFC 8414)","tags":["Discovery"],"responses":{"200":{"description":"Default Response"}}}},"/.well-known/oauth-protected-resource":{"get":{"operationId":"getProtectedResourceMetadata","summary":"Protected resource metadata (RFC 9728)","tags":["Discovery"],"responses":{"200":{"description":"Default Response"}}}},"/.well-known/snappy-agents.json":{"get":{"operationId":"getConnectorManifest","summary":"Connector manifest: endpoints, scopes, tool classification and example prompts","tags":["Discovery"],"responses":{"200":{"description":"Default Response"}}}},"/oauth/authorize":{"get":{"operationId":"authorize","summary":"Authorization endpoint (browser)","tags":["OAuth"],"parameters":[{"schema":{"type":"string"},"in":"query","name":"response_type","required":false},{"schema":{"type":"string"},"in":"query","name":"client_id","required":false},{"schema":{"type":"string"},"in":"query","name":"redirect_uri","required":false},{"schema":{"type":"string"},"in":"query","name":"scope","required":false},{"schema":{"type":"string"},"in":"query","name":"state","required":false},{"schema":{"type":"string"},"in":"query","name":"code_challenge","required":false},{"schema":{"type":"string"},"in":"query","name":"code_challenge_method","required":false},{"schema":{"type":"string"},"in":"query","name":"resource","required":false},{"schema":{"type":"string"},"in":"query","name":"prompt","required":false}],"responses":{"200":{"description":"Default Response"}}}},"/oauth/token":{"post":{"operationId":"token","summary":"Token endpoint (authorization_code with PKCE, refresh_token)","tags":["OAuth"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"grant_type":{"type":"string"},"code":{"type":"string"},"code_verifier":{"type":"string"},"redirect_uri":{"type":"string"},"refresh_token":{"type":"string"},"client_id":{"type":"string"},"client_secret":{"type":"string"},"scope":{"type":"string"}},"required":["grant_type"]}}}},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"access_token":{"type":"string"},"token_type":{"type":"string","enum":["Bearer"]},"expires_in":{"type":"number"},"scope":{"type":"string"},"refresh_token":{"type":"string"}},"required":["access_token","token_type","expires_in","scope"],"additionalProperties":false}}}}}}},"/oauth/register":{"post":{"operationId":"registerClient","summary":"Dynamic client registration (RFC 7591)","tags":["OAuth"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"client_name":{"type":"string","minLength":1,"maxLength":100},"redirect_uris":{"minItems":1,"maxItems":10,"type":"array","items":{"type":"string","format":"uri"}},"grant_types":{"type":"array","items":{"type":"string"}},"response_types":{"type":"array","items":{"type":"string"}},"token_endpoint_auth_method":{"type":"string","enum":["none","client_secret_post","client_secret_basic"]},"scope":{"type":"string"},"logo_uri":{"type":"string","format":"uri"},"client_uri":{"type":"string","format":"uri"},"contacts":{"type":"array","items":{"type":"string"}},"software_id":{"type":"string"}},"required":["client_name","redirect_uris"]}}}},"responses":{"200":{"description":"Default Response"}}}},"/oauth/revoke":{"post":{"operationId":"revokeToken","summary":"Revoke a token and its family (RFC 7009)","tags":["OAuth"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"token":{"type":"string"},"token_type_hint":{"type":"string"},"client_id":{"type":"string"},"client_secret":{"type":"string"}},"required":["token"]}}}},"responses":{"200":{"description":"Default Response"}}}},"/oauth/introspect":{"post":{"operationId":"introspectToken","summary":"Token introspection (RFC 7662)","tags":["OAuth"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"token":{"type":"string"},"client_id":{"type":"string"},"client_secret":{"type":"string"}},"required":["token"]}}}},"responses":{"200":{"description":"Default Response"}}}},"/v1/search":{"get":{"operationId":"searchCatalog","summary":"Search the marketplace (products + collections) with natural-language budget","tags":["Catalog"],"description":"One call for 'find me X under $50 that ships to Canada'. `budget` accepts prose ('under $50', 'between 20 and 40', 'around 100'); `minPrice`/`maxPrice` override it. Prices are what the user would pay, before the per-country landed total you get from availability.","parameters":[{"schema":{"type":"string","maxLength":200},"in":"query","name":"q","required":false,"description":"Free text: product, brand, category or occasion"},{"schema":{"type":"string","maxLength":60},"in":"query","name":"budget","required":false,"description":"Prose budget, e.g. 'under $50'"},{"schema":{"type":"number","minimum":0},"in":"query","name":"minPrice","required":false},{"schema":{"type":"number","minimum":0},"in":"query","name":"maxPrice","required":false},{"schema":{"type":"string","pattern":"^[A-Za-z]{2}$"},"in":"query","name":"country","required":false,"description":"ISO country to price for; defaults to the user's country"},{"schema":{"type":"string"},"in":"query","name":"collectionId","required":false},{"schema":{"type":"string"},"in":"query","name":"tagIds","required":false,"description":"Comma-separated tag ids"},{"schema":{"type":"string","enum":["relevance","price_asc","price_desc","newest"]},"in":"query","name":"sort","required":false},{"schema":{"type":"integer","minimum":1,"maximum":50},"in":"query","name":"limit","required":false},{"schema":{"type":"string"},"in":"query","name":"cursor","required":false}],"security":[{"oauth2":["catalog:read"]}],"x-tool-class":"read","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"products":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"brand":{"type":["string","null"]},"category":{"type":"string"},"catalog":{"type":"string"},"imageUrl":{"type":["string","null"]},"images":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}},"priceRange":{"anyOf":[{"type":"object","properties":{"min":{"type":"object","properties":{"amount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Minor units (cents)"},"currency":{"type":"string","minLength":3,"maxLength":3},"display":{"type":"string","description":"Formatted for humans, e.g. $24.99"}},"required":["amount","currency","display"],"additionalProperties":false},"max":{"type":"object","properties":{"amount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Minor units (cents)"},"currency":{"type":"string","minLength":3,"maxLength":3},"display":{"type":"string","description":"Formatted for humans, e.g. $24.99"}},"required":["amount","currency","display"],"additionalProperties":false}},"required":["min","max"],"additionalProperties":false},{"type":"null"}]},"variantsCount":{"type":["number","null"]},"options":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"displayName":{"type":"string"},"values":{"type":"array","items":{"type":"string"}}},"required":["name","displayName","values"],"additionalProperties":false}},"defaultVariantId":{"description":"Set when the product has exactly one purchasable variant; quote this directly","type":["string","null"]}},"required":["id","title","brand","category","catalog","imageUrl","images","tags","priceRange","variantsCount","options","defaultVariantId"],"additionalProperties":false}},"collections":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"imageUrl":{"type":["string","null"]},"priceRange":{"anyOf":[{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"required":["min","max"],"additionalProperties":false},{"type":"null"}]},"tags":{"type":"array","items":{"type":"string"}}},"required":["id","name","description","imageUrl","priceRange","tags"],"additionalProperties":false}},"nextCursor":{"type":["string","null"]},"appliedFilters":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["products","collections","nextCursor","appliedFilters"],"additionalProperties":false}}}}}}},"/v1/products/{productId}":{"get":{"operationId":"getProduct","summary":"Product detail with variants and recommendations","tags":["Catalog"],"parameters":[{"schema":{"type":"string","pattern":"^[A-Za-z]{2}$"},"in":"query","name":"country","required":false,"description":"ISO country to price for; defaults to the user's country"},{"schema":{"type":"string"},"in":"path","name":"productId","required":true}],"security":[{"oauth2":["catalog:read"]}],"x-tool-class":"read","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"product":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"brand":{"type":["string","null"]},"category":{"type":"string"},"catalog":{"type":"string"},"imageUrl":{"type":["string","null"]},"images":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}},"priceRange":{"anyOf":[{"type":"object","properties":{"min":{"type":"object","properties":{"amount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Minor units (cents)"},"currency":{"type":"string","minLength":3,"maxLength":3},"display":{"type":"string","description":"Formatted for humans, e.g. $24.99"}},"required":["amount","currency","display"],"additionalProperties":false},"max":{"type":"object","properties":{"amount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Minor units (cents)"},"currency":{"type":"string","minLength":3,"maxLength":3},"display":{"type":"string","description":"Formatted for humans, e.g. $24.99"}},"required":["amount","currency","display"],"additionalProperties":false}},"required":["min","max"],"additionalProperties":false},{"type":"null"}]},"variantsCount":{"type":["number","null"]},"options":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"displayName":{"type":"string"},"values":{"type":"array","items":{"type":"string"}}},"required":["name","displayName","values"],"additionalProperties":false}},"defaultVariantId":{"description":"Set when the product has exactly one purchasable variant; quote this directly","type":["string","null"]}},"required":["id","title","brand","category","catalog","imageUrl","images","tags","priceRange","variantsCount","options","defaultVariantId"],"additionalProperties":false},"variants":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"productId":{"type":"string"},"title":{"type":"string"},"selectedOptions":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}},"imageUrl":{"type":["string","null"]},"price":{"anyOf":[{"type":"object","properties":{"amount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Minor units (cents)"},"currency":{"type":"string","minLength":3,"maxLength":3},"display":{"type":"string","description":"Formatted for humans, e.g. $24.99"}},"required":["amount","currency","display"],"additionalProperties":false},{"type":"null"}]},"shippingRequired":{"type":"boolean"},"isDigital":{"type":"boolean"},"personalizationRequired":{"type":"boolean"},"descriptionHtml":{"type":["string","null"]},"details":{"anyOf":[{},{"type":"null"}]}},"required":["id","productId","title","selectedOptions","imageUrl","price","shippingRequired","isDigital","personalizationRequired","descriptionHtml","details"],"additionalProperties":false}},"recommendations":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"brand":{"type":["string","null"]},"category":{"type":"string"},"catalog":{"type":"string"},"imageUrl":{"type":["string","null"]},"images":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}},"priceRange":{"anyOf":[{"type":"object","properties":{"min":{"type":"object","properties":{"amount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Minor units (cents)"},"currency":{"type":"string","minLength":3,"maxLength":3},"display":{"type":"string","description":"Formatted for humans, e.g. $24.99"}},"required":["amount","currency","display"],"additionalProperties":false},"max":{"type":"object","properties":{"amount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Minor units (cents)"},"currency":{"type":"string","minLength":3,"maxLength":3},"display":{"type":"string","description":"Formatted for humans, e.g. $24.99"}},"required":["amount","currency","display"],"additionalProperties":false}},"required":["min","max"],"additionalProperties":false},{"type":"null"}]},"variantsCount":{"type":["number","null"]},"options":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"displayName":{"type":"string"},"values":{"type":"array","items":{"type":"string"}}},"required":["name","displayName","values"],"additionalProperties":false}},"defaultVariantId":{"description":"Set when the product has exactly one purchasable variant; quote this directly","type":["string","null"]}},"required":["id","title","brand","category","catalog","imageUrl","images","tags","priceRange","variantsCount","options","defaultVariantId"],"additionalProperties":false}}},"required":["product","variants","recommendations"],"additionalProperties":false}}}}}}},"/v1/variants/{variantId}":{"get":{"operationId":"getVariant","summary":"Variant detail","tags":["Catalog"],"parameters":[{"schema":{"type":"string","pattern":"^[A-Za-z]{2}$"},"in":"query","name":"country","required":false,"description":"ISO country to price for; defaults to the user's country"},{"schema":{"type":"string"},"in":"path","name":"variantId","required":true}],"security":[{"oauth2":["catalog:read"]}],"x-tool-class":"read","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"productId":{"type":"string"},"title":{"type":"string"},"selectedOptions":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}},"imageUrl":{"type":["string","null"]},"price":{"anyOf":[{"type":"object","properties":{"amount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Minor units (cents)"},"currency":{"type":"string","minLength":3,"maxLength":3},"display":{"type":"string","description":"Formatted for humans, e.g. $24.99"}},"required":["amount","currency","display"],"additionalProperties":false},{"type":"null"}]},"shippingRequired":{"type":"boolean"},"isDigital":{"type":"boolean"},"personalizationRequired":{"type":"boolean"},"descriptionHtml":{"type":["string","null"]},"details":{"anyOf":[{},{"type":"null"}]}},"required":["id","productId","title","selectedOptions","imageUrl","price","shippingRequired","isDigital","personalizationRequired","descriptionHtml","details"],"additionalProperties":false}}}}}}},"/v1/variants/{variantId}/availability":{"get":{"operationId":"getVariantAvailability","summary":"Live availability and all-in price per country","tags":["Catalog"],"description":"Call this right before quoting. `price` is the exact amount the user will be charged (item + shipping + duties + service fee).","parameters":[{"schema":{"type":"string"},"in":"query","name":"countries","required":false,"description":"Comma-separated ISO codes; default = all supported"},{"schema":{"type":"string"},"in":"path","name":"variantId","required":true}],"security":[{"oauth2":["catalog:read"]}],"x-tool-class":"read","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"variantId":{"type":"string"},"countries":{"type":"array","items":{"type":"object","properties":{"countryCode":{"type":"string"},"available":{"type":"boolean"},"price":{"type":"object","properties":{"amount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Minor units (cents)"},"currency":{"type":"string","minLength":3,"maxLength":3},"display":{"type":"string","description":"Formatted for humans, e.g. $24.99"}},"required":["amount","currency","display"],"additionalProperties":false,"description":"What the user pays, all-in"},"breakdown":{"type":"object","properties":{"item":{"type":"object","properties":{"amount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Minor units (cents)"},"currency":{"type":"string","minLength":3,"maxLength":3},"display":{"type":"string","description":"Formatted for humans, e.g. $24.99"}},"required":["amount","currency","display"],"additionalProperties":false},"shipping":{"type":"object","properties":{"amount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Minor units (cents)"},"currency":{"type":"string","minLength":3,"maxLength":3},"display":{"type":"string","description":"Formatted for humans, e.g. $24.99"}},"required":["amount","currency","display"],"additionalProperties":false},"duties":{"type":"object","properties":{"amount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Minor units (cents)"},"currency":{"type":"string","minLength":3,"maxLength":3},"display":{"type":"string","description":"Formatted for humans, e.g. $24.99"}},"required":["amount","currency","display"],"additionalProperties":false},"serviceFee":{"type":"object","properties":{"amount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Minor units (cents)"},"currency":{"type":"string","minLength":3,"maxLength":3},"display":{"type":"string","description":"Formatted for humans, e.g. $24.99"}},"required":["amount","currency","display"],"additionalProperties":false},"total":{"type":"object","properties":{"amount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Minor units (cents)"},"currency":{"type":"string","minLength":3,"maxLength":3},"display":{"type":"string","description":"Formatted for humans, e.g. $24.99"}},"required":["amount","currency","display"],"additionalProperties":false}},"required":["item","shipping","duties","serviceFee","total"],"additionalProperties":false}},"required":["countryCode","available","price","breakdown"],"additionalProperties":false}}},"required":["variantId","countries"],"additionalProperties":false}}}}}}},"/v1/collections":{"get":{"operationId":"listCollections","summary":"Curated collections (by occasion, budget, theme)","tags":["Catalog"],"parameters":[{"schema":{"type":"string"},"in":"query","name":"q","required":false},{"schema":{"type":"number"},"in":"query","name":"maxPrice","required":false},{"schema":{"type":"string","pattern":"^[A-Za-z]{2}$"},"in":"query","name":"country","required":false,"description":"ISO country to price for; defaults to the user's country"},{"schema":{"type":"integer","minimum":1,"maximum":100},"in":"query","name":"limit","required":false}],"security":[{"oauth2":["catalog:read"]}],"x-tool-class":"read","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"collections":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"imageUrl":{"type":["string","null"]},"priceRange":{"anyOf":[{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"required":["min","max"],"additionalProperties":false},{"type":"null"}]},"tags":{"type":"array","items":{"type":"string"}}},"required":["id","name","description","imageUrl","priceRange","tags"],"additionalProperties":false}}},"required":["collections"],"additionalProperties":false}}}}}}},"/v1/collections/{collectionId}":{"get":{"operationId":"getCollection","summary":"Collection with its products","tags":["Catalog"],"parameters":[{"schema":{"type":"string","pattern":"^[A-Za-z]{2}$"},"in":"query","name":"country","required":false,"description":"ISO country to price for; defaults to the user's country"},{"schema":{"type":"integer","minimum":1,"maximum":100},"in":"query","name":"limit","required":false},{"schema":{"type":"string"},"in":"query","name":"cursor","required":false},{"schema":{"type":"number"},"in":"query","name":"minPrice","required":false},{"schema":{"type":"number"},"in":"query","name":"maxPrice","required":false},{"schema":{"type":"string"},"in":"path","name":"collectionId","required":true}],"security":[{"oauth2":["catalog:read"]}],"x-tool-class":"read","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"collection":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"imageUrl":{"type":["string","null"]},"priceRange":{"anyOf":[{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"required":["min","max"],"additionalProperties":false},{"type":"null"}]},"tags":{"type":"array","items":{"type":"string"}}},"required":["id","name","description","imageUrl","priceRange","tags"],"additionalProperties":false},"products":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"brand":{"type":["string","null"]},"category":{"type":"string"},"catalog":{"type":"string"},"imageUrl":{"type":["string","null"]},"images":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}},"priceRange":{"anyOf":[{"type":"object","properties":{"min":{"type":"object","properties":{"amount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Minor units (cents)"},"currency":{"type":"string","minLength":3,"maxLength":3},"display":{"type":"string","description":"Formatted for humans, e.g. $24.99"}},"required":["amount","currency","display"],"additionalProperties":false},"max":{"type":"object","properties":{"amount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Minor units (cents)"},"currency":{"type":"string","minLength":3,"maxLength":3},"display":{"type":"string","description":"Formatted for humans, e.g. $24.99"}},"required":["amount","currency","display"],"additionalProperties":false}},"required":["min","max"],"additionalProperties":false},{"type":"null"}]},"variantsCount":{"type":["number","null"]},"options":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"displayName":{"type":"string"},"values":{"type":"array","items":{"type":"string"}}},"required":["name","displayName","values"],"additionalProperties":false}},"defaultVariantId":{"description":"Set when the product has exactly one purchasable variant; quote this directly","type":["string","null"]}},"required":["id","title","brand","category","catalog","imageUrl","images","tags","priceRange","variantsCount","options","defaultVariantId"],"additionalProperties":false}},"nextCursor":{"type":["string","null"]}},"required":["collection","products","nextCursor"],"additionalProperties":false}}}}}}},"/v1/tags":{"get":{"operationId":"listTags","summary":"Product tags for filtering","tags":["Catalog"],"parameters":[{"schema":{"type":"string","minLength":3},"in":"query","name":"q","required":false}],"security":[{"oauth2":["catalog:read"]}],"x-tool-class":"read","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"tags":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false}}},"required":["tags"],"additionalProperties":false}}}}}}},"/v1/countries":{"get":{"operationId":"listCountries","summary":"Countries the platform ships to","tags":["Catalog"],"security":[{"oauth2":["catalog:read"]}],"x-tool-class":"read","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"countries":{"type":"array","items":{"type":"string"}}},"required":["countries"],"additionalProperties":false}}}}}}},"/v1/addresses/autocomplete":{"get":{"operationId":"autocompleteAddress","summary":"Address autocomplete (helps collect a shippable address quickly)","tags":["Catalog"],"parameters":[{"schema":{"type":"string","minLength":4,"maxLength":128},"in":"query","name":"q","required":true},{"schema":{"type":"string","pattern":"^[A-Za-z]{2}$"},"in":"query","name":"country","required":true}],"security":[{"oauth2":["catalog:read"]}],"x-tool-class":"read","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"suggestions":{"type":"array","items":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}}}},"required":["suggestions"],"additionalProperties":false}}}}}}},"/v1/addresses/validate":{"post":{"operationId":"validateAddress","summary":"Validate a shipping address before checkout","tags":["Catalog"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"address":{"type":"object","properties":{"address1":{"type":"string"},"address2":{"type":"string"},"city":{"type":"string"},"provinceCode":{"type":"string"},"postalCode":{"type":"string"},"countryCode":{"type":"string","pattern":"^[A-Za-z]{2}$"}},"required":["countryCode"]}},"required":["address"]}}}},"security":[{"oauth2":["catalog:read"]}],"x-tool-class":"read","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"string","enum":["verified","ambiguous"]},"message":{"type":"string"}},"required":["result","message"],"additionalProperties":false}}}}}}},"/v1/me":{"get":{"operationId":"getMe","summary":"The signed-in user and their saved addresses","tags":["Profile"],"security":[{"oauth2":["profile"]}],"x-tool-class":"read","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"user":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"displayName":{"type":["string","null"]},"phone":{"type":["string","null"]},"defaultCountry":{"type":"string"},"receiptPreference":{"type":"string"},"createdAt":{"type":"string"}},"required":["id","email","displayName","phone","defaultCountry","receiptPreference","createdAt"],"additionalProperties":false},"addresses":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":["string","null"]},"firstName":{"type":"string"},"lastName":{"type":"string"},"phone":{"type":["string","null"]},"address1":{"type":["string","null"]},"address2":{"type":["string","null"]},"city":{"type":["string","null"]},"provinceCode":{"type":["string","null"]},"postalCode":{"type":["string","null"]},"countryCode":{"type":"string"},"isDefault":{"type":"boolean"}},"required":["id","label","firstName","lastName","phone","address1","address2","city","provinceCode","postalCode","countryCode","isDefault"],"additionalProperties":false}},"scopes":{"type":"array","items":{"type":"string"}}},"required":["user","addresses","scopes"],"additionalProperties":false}}}}}},"patch":{"operationId":"updateMe","summary":"Update display name, phone, default country or receipt preference","tags":["Profile"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"displayName":{"anyOf":[{"type":"string","maxLength":80},{"type":"null"}]},"phone":{"anyOf":[{"type":"string","maxLength":20},{"type":"null"}]},"defaultCountry":{"type":"string","pattern":"^[A-Za-z]{2}$"},"receiptPreference":{"type":"string","enum":["email","sms","both","none"]}}}}}},"security":[{"oauth2":["profile"]}],"x-tool-class":"write","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"displayName":{"type":["string","null"]},"phone":{"type":["string","null"]},"defaultCountry":{"type":"string"},"receiptPreference":{"type":"string"},"createdAt":{"type":"string"}},"required":["id","email","displayName","phone","defaultCountry","receiptPreference","createdAt"],"additionalProperties":false}}}}}}},"/v1/me/addresses":{"post":{"operationId":"addAddress","summary":"Save a shipping address for reuse","tags":["Profile"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"type":"string","maxLength":40},"firstName":{"type":"string","minLength":1},"lastName":{"type":"string","minLength":1},"phone":{"type":"string"},"address1":{"type":"string"},"address2":{"type":"string"},"city":{"type":"string"},"provinceCode":{"type":"string"},"postalCode":{"type":"string"},"countryCode":{"type":"string","pattern":"^[A-Za-z]{2}$"},"isDefault":{"type":"boolean"}},"required":["firstName","lastName","countryCode"]}}}},"security":[{"oauth2":["profile"]}],"x-tool-class":"write","responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":["string","null"]},"firstName":{"type":"string"},"lastName":{"type":"string"},"phone":{"type":["string","null"]},"address1":{"type":["string","null"]},"address2":{"type":["string","null"]},"city":{"type":["string","null"]},"provinceCode":{"type":["string","null"]},"postalCode":{"type":["string","null"]},"countryCode":{"type":"string"},"isDefault":{"type":"boolean"}},"required":["id","label","firstName","lastName","phone","address1","address2","city","provinceCode","postalCode","countryCode","isDefault"],"additionalProperties":false}}}}}}},"/v1/me/addresses/{addressId}":{"delete":{"operationId":"deleteAddress","summary":"Delete a saved address","tags":["Profile"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"addressId","required":true}],"security":[{"oauth2":["profile"]}],"x-tool-class":"write","responses":{"204":{"description":"Default Response"}}}},"/v1/quotes":{"post":{"operationId":"createQuote","summary":"Create a price quote for one variant shipped to one country","tags":["Checkout"],"description":"Returns the exact all-in amount (item + shipping + duties + service fee) and locks it for 15 minutes. Create one quote per cart line, then pass them all to createCheckout. Show `totalDisplay` to the user before checkout.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"variantId":{"type":"string"},"countryCode":{"type":"string","pattern":"^[A-Za-z]{2}$"}},"required":["variantId"]}}}},"security":[{"oauth2":["orders:write"]}],"x-tool-class":"write","responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"variantId":{"type":"string"},"productId":{"type":"string"},"productTitle":{"type":"string"},"variantTitle":{"type":"string"},"imageUrl":{"type":["string","null"]},"countryCode":{"type":"string"},"quantity":{"type":"number"},"currency":{"type":"string"},"itemAmount":{"type":"number"},"shippingAmount":{"type":"number"},"dutiesAmount":{"type":"number"},"serviceFeeAmount":{"type":"number"},"totalAmount":{"type":"number"},"totalDisplay":{"type":"string"},"shippingRequired":{"type":"boolean"},"expiresAt":{"type":"string"}},"required":["id","variantId","productId","productTitle","variantTitle","imageUrl","countryCode","quantity","currency","itemAmount","shippingAmount","dutiesAmount","serviceFeeAmount","totalAmount","totalDisplay","shippingRequired","expiresAt"],"additionalProperties":false}}}}}}},"/v1/quotes/{quoteId}":{"get":{"operationId":"getQuote","summary":"Get a quote","tags":["Checkout"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"quoteId","required":true}],"security":[{"oauth2":["orders:read"]}],"x-tool-class":"read","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"variantId":{"type":"string"},"productId":{"type":"string"},"productTitle":{"type":"string"},"variantTitle":{"type":"string"},"imageUrl":{"type":["string","null"]},"countryCode":{"type":"string"},"quantity":{"type":"number"},"currency":{"type":"string"},"itemAmount":{"type":"number"},"shippingAmount":{"type":"number"},"dutiesAmount":{"type":"number"},"serviceFeeAmount":{"type":"number"},"totalAmount":{"type":"number"},"totalDisplay":{"type":"string"},"shippingRequired":{"type":"boolean"},"expiresAt":{"type":"string"}},"required":["id","variantId","productId","productTitle","variantTitle","imageUrl","countryCode","quantity","currency","itemAmount","shippingAmount","dutiesAmount","serviceFeeAmount","totalAmount","totalDisplay","shippingRequired","expiresAt"],"additionalProperties":false}}}}}}},"/v1/checkouts":{"post":{"operationId":"createCheckout","summary":"Create a checkout for a cart of quotes: returns one hosted Stripe payment link (SENSITIVE WRITE)","tags":["Checkout"],"description":"Creates one payment session for all `items` (each a quote, optionally with quantity). Snappy places one order per item after payment. The user must open `paymentUrl` and pay on Stripe; nothing is charged by this call. Always confirm with the user first: items, total, recipient and address. All quotes must be for the same country. Physical items need a full, verified address (use /addresses/validate). Digital-only carts need only `countryCode`. SMS notifications require explicit consent: pass `smsConsent: true` only after the user agreed to the consent text returned by error `sms_consent_required`. After the user pays, poll `statusUrl` or stream `eventsUrl` until `status` is `confirmed` or `partially_confirmed` (usually seconds).","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"items":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"object","properties":{"quoteId":{"type":"string"},"quantity":{"type":"integer","minimum":1,"maximum":10}},"required":["quoteId"]}},"recipient":{"type":"object","properties":{"firstName":{"type":"string","minLength":1,"maxLength":60},"lastName":{"type":"string","minLength":1,"maxLength":60},"email":{"type":"string","format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"phone":{"type":"string","minLength":7,"maxLength":20,"description":"E.164, e.g. +15551234567. Carriers use it for delivery."}},"required":["firstName","lastName","email","phone"],"description":"Who receives the package (the buyer, or someone else)"},"shippingAddress":{"type":"object","properties":{"address1":{"type":"string","minLength":1,"maxLength":200},"address2":{"type":"string","maxLength":200},"city":{"type":"string","minLength":1,"maxLength":100},"provinceCode":{"description":"State/province code, e.g. NY","type":"string","maxLength":10},"postalCode":{"type":"string","maxLength":20},"countryCode":{"type":"string","pattern":"^[A-Za-z]{2}$","description":"ISO 3166-1 alpha-2"}},"required":["countryCode"]},"notify":{"type":"object","properties":{"email":{"description":"Where to send confirmation + receipt; defaults to the buyer's email; null disables","anyOf":[{"type":"string","format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},{"type":"null"}]},"sms":{"description":"E.164 number for SMS confirmation (needs smsConsent)","type":["string","null"]}}},"smsConsent":{"description":"True once the user agreed to the SMS consent text","type":"boolean"},"callbackUrl":{"description":"Optional HTTPS URL we POST signed status events to","anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"idempotencyKey":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}]}},"required":["items","recipient","shippingAddress"]}}}},"security":[{"oauth2":["orders:write"]}],"x-tool-class":"sensitive-write","responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["pending_payment","paid","placing","confirmed","partially_confirmed","failed","refunded","expired","cancelled"]},"items":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"quoteId":{"type":"string"},"variantId":{"type":"string"},"productTitle":{"type":"string"},"variantTitle":{"type":"string"},"imageUrl":{"type":["string","null"]},"amount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"amountDisplay":{"type":"string"},"status":{"type":"string","enum":["pending","placed","failed","refunded"]},"orderId":{"type":["string","null"]},"failureReason":{"type":["string","null"]}},"required":["index","quoteId","variantId","productTitle","variantTitle","imageUrl","amount","amountDisplay","status","orderId","failureReason"],"additionalProperties":false}},"paymentUrl":{"description":"Hosted Stripe Checkout link. Hand this to the user; never collect card details yourself.","type":["string","null"]},"expiresAt":{"type":"string"},"totalAmount":{"type":"number"},"currency":{"type":"string"},"totalDisplay":{"type":"string"},"refundedAmount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"orderIds":{"type":"array","items":{"type":"string"},"description":"Orders created so far (one per placed item)"},"failureReason":{"type":["string","null"]},"statusUrl":{"type":"string"},"eventsUrl":{"type":"string"},"nextStep":{"type":"string","description":"Plain-language instruction for the agent"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","status","items","paymentUrl","expiresAt","totalAmount","currency","totalDisplay","refundedAmount","orderIds","failureReason","statusUrl","eventsUrl","nextStep","createdAt","updatedAt"],"additionalProperties":false}}}}}},"get":{"operationId":"listCheckouts","summary":"List recent checkouts","tags":["Checkout"],"security":[{"oauth2":["orders:read"]}],"x-tool-class":"read","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"checkouts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["pending_payment","paid","placing","confirmed","partially_confirmed","failed","refunded","expired","cancelled"]},"items":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"quoteId":{"type":"string"},"variantId":{"type":"string"},"productTitle":{"type":"string"},"variantTitle":{"type":"string"},"imageUrl":{"type":["string","null"]},"amount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"amountDisplay":{"type":"string"},"status":{"type":"string","enum":["pending","placed","failed","refunded"]},"orderId":{"type":["string","null"]},"failureReason":{"type":["string","null"]}},"required":["index","quoteId","variantId","productTitle","variantTitle","imageUrl","amount","amountDisplay","status","orderId","failureReason"],"additionalProperties":false}},"paymentUrl":{"description":"Hosted Stripe Checkout link. Hand this to the user; never collect card details yourself.","type":["string","null"]},"expiresAt":{"type":"string"},"totalAmount":{"type":"number"},"currency":{"type":"string"},"totalDisplay":{"type":"string"},"refundedAmount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"orderIds":{"type":"array","items":{"type":"string"},"description":"Orders created so far (one per placed item)"},"failureReason":{"type":["string","null"]},"statusUrl":{"type":"string"},"eventsUrl":{"type":"string"},"nextStep":{"type":"string","description":"Plain-language instruction for the agent"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","status","items","paymentUrl","expiresAt","totalAmount","currency","totalDisplay","refundedAmount","orderIds","failureReason","statusUrl","eventsUrl","nextStep","createdAt","updatedAt"],"additionalProperties":false}}},"required":["checkouts"],"additionalProperties":false}}}}}}},"/v1/checkouts/{checkoutId}":{"get":{"operationId":"getCheckout","summary":"Checkout status (poll this after the user pays)","tags":["Checkout"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"checkoutId","required":true}],"security":[{"oauth2":["orders:read"]}],"x-tool-class":"read","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["pending_payment","paid","placing","confirmed","partially_confirmed","failed","refunded","expired","cancelled"]},"items":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"quoteId":{"type":"string"},"variantId":{"type":"string"},"productTitle":{"type":"string"},"variantTitle":{"type":"string"},"imageUrl":{"type":["string","null"]},"amount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"amountDisplay":{"type":"string"},"status":{"type":"string","enum":["pending","placed","failed","refunded"]},"orderId":{"type":["string","null"]},"failureReason":{"type":["string","null"]}},"required":["index","quoteId","variantId","productTitle","variantTitle","imageUrl","amount","amountDisplay","status","orderId","failureReason"],"additionalProperties":false}},"paymentUrl":{"description":"Hosted Stripe Checkout link. Hand this to the user; never collect card details yourself.","type":["string","null"]},"expiresAt":{"type":"string"},"totalAmount":{"type":"number"},"currency":{"type":"string"},"totalDisplay":{"type":"string"},"refundedAmount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"orderIds":{"type":"array","items":{"type":"string"},"description":"Orders created so far (one per placed item)"},"failureReason":{"type":["string","null"]},"statusUrl":{"type":"string"},"eventsUrl":{"type":"string"},"nextStep":{"type":"string","description":"Plain-language instruction for the agent"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","status","items","paymentUrl","expiresAt","totalAmount","currency","totalDisplay","refundedAmount","orderIds","failureReason","statusUrl","eventsUrl","nextStep","createdAt","updatedAt"],"additionalProperties":false}}}}}}},"/v1/checkouts/{checkoutId}/receipt":{"post":{"operationId":"sendCheckoutReceipt","summary":"Send the receipt for the whole purchase by email or SMS","tags":["Checkout"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"channel":{"type":"string","enum":["email","sms"]},"to":{"type":"string"},"smsConsent":{"type":"boolean"}},"required":["channel"]}}}},"parameters":[{"schema":{"type":"string"},"in":"path","name":"checkoutId","required":true}],"security":[{"oauth2":["orders:write"]}],"x-tool-class":"write","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"sentTo":{"type":"string"},"channel":{"type":"string"}},"required":["sentTo","channel"],"additionalProperties":false}}}}}}},"/v1/checkouts/{checkoutId}/cancel":{"post":{"operationId":"cancelCheckout","summary":"Cancel an unpaid checkout (SENSITIVE WRITE)","tags":["Checkout"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"checkoutId","required":true}],"security":[{"oauth2":["orders:write"]}],"x-tool-class":"sensitive-write","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["pending_payment","paid","placing","confirmed","partially_confirmed","failed","refunded","expired","cancelled"]},"items":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"quoteId":{"type":"string"},"variantId":{"type":"string"},"productTitle":{"type":"string"},"variantTitle":{"type":"string"},"imageUrl":{"type":["string","null"]},"amount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"amountDisplay":{"type":"string"},"status":{"type":"string","enum":["pending","placed","failed","refunded"]},"orderId":{"type":["string","null"]},"failureReason":{"type":["string","null"]}},"required":["index","quoteId","variantId","productTitle","variantTitle","imageUrl","amount","amountDisplay","status","orderId","failureReason"],"additionalProperties":false}},"paymentUrl":{"description":"Hosted Stripe Checkout link. Hand this to the user; never collect card details yourself.","type":["string","null"]},"expiresAt":{"type":"string"},"totalAmount":{"type":"number"},"currency":{"type":"string"},"totalDisplay":{"type":"string"},"refundedAmount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"orderIds":{"type":"array","items":{"type":"string"},"description":"Orders created so far (one per placed item)"},"failureReason":{"type":["string","null"]},"statusUrl":{"type":"string"},"eventsUrl":{"type":"string"},"nextStep":{"type":"string","description":"Plain-language instruction for the agent"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","status","items","paymentUrl","expiresAt","totalAmount","currency","totalDisplay","refundedAmount","orderIds","failureReason","statusUrl","eventsUrl","nextStep","createdAt","updatedAt"],"additionalProperties":false}}}}}}},"/v1/checkouts/{checkoutId}/timeline":{"get":{"operationId":"getCheckoutTimeline","summary":"Event timeline for a checkout","tags":["Checkout"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"checkoutId","required":true}],"security":[{"oauth2":["orders:read"]}],"x-tool-class":"read","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"events":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"data":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"createdAt":{"type":"string"}},"required":["id","type","data","createdAt"],"additionalProperties":false}}},"required":["events"],"additionalProperties":false}}}}}}},"/v1/checkouts/{checkoutId}/events":{"get":{"operationId":"streamCheckoutEvents","summary":"Real-time status stream (Server-Sent Events)","tags":["Checkout"],"description":"`text/event-stream`. Each event: `id`, `event: <type>`, `data: {...}`. Ends with `event: done` once the checkout reaches a terminal state.","parameters":[{"schema":{"type":"string"},"in":"path","name":"checkoutId","required":true}],"security":[{"oauth2":["orders:read"]}],"x-tool-class":"read","responses":{"200":{"description":"Default Response"}}}},"/v1/orders":{"get":{"operationId":"listOrders","summary":"List the user's orders, newest first","tags":["Orders"],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":50},"in":"query","name":"limit","required":false}],"security":[{"oauth2":["orders:read"]}],"x-tool-class":"read","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"orders":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"snappyOrderId":{"type":"string"},"stage":{"type":"string","enum":["confirmed","processing","shipped","out_for_delivery","delivered","cancelled","refunded"]},"productTitle":{"type":"string"},"variantTitle":{"type":"string"},"imageUrl":{"type":["string","null"]},"checkoutId":{"type":"string"},"recipientName":{"type":"string"},"shippingAddress":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":["string","null"]}},"totalAmount":{"type":"number"},"currency":{"type":"string"},"totalDisplay":{"type":"string"},"tracking":{"type":"object","properties":{"link":{"type":["string","null"]},"company":{"type":["string","null"]},"number":{"type":["string","null"]},"url":{"type":["string","null"]}},"required":["link","company","number","url"],"additionalProperties":false},"cancellable":{"type":"boolean"},"nextActions":{"type":"array","items":{"type":"string","enum":["cancel","request_support","track"]},"description":"What the agent can offer right now"},"refundedAmount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"refundId":{"type":["string","null"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","snappyOrderId","stage","productTitle","variantTitle","imageUrl","checkoutId","recipientName","shippingAddress","totalAmount","currency","totalDisplay","tracking","cancellable","nextActions","refundedAmount","refundId","createdAt","updatedAt"],"additionalProperties":false}}},"required":["orders"],"additionalProperties":false}}}}}}},"/v1/orders/{orderId}":{"get":{"operationId":"getOrder","summary":"Order detail with live tracking","tags":["Orders"],"description":"Set `refresh=true` to pull the latest fulfilment state from Snappy (otherwise webhooks keep it current).","parameters":[{"schema":{"type":"boolean"},"in":"query","name":"refresh","required":false},{"schema":{"type":"string"},"in":"path","name":"orderId","required":true}],"security":[{"oauth2":["orders:read"]}],"x-tool-class":"read","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"snappyOrderId":{"type":"string"},"stage":{"type":"string","enum":["confirmed","processing","shipped","out_for_delivery","delivered","cancelled","refunded"]},"productTitle":{"type":"string"},"variantTitle":{"type":"string"},"imageUrl":{"type":["string","null"]},"checkoutId":{"type":"string"},"recipientName":{"type":"string"},"shippingAddress":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":["string","null"]}},"totalAmount":{"type":"number"},"currency":{"type":"string"},"totalDisplay":{"type":"string"},"tracking":{"type":"object","properties":{"link":{"type":["string","null"]},"company":{"type":["string","null"]},"number":{"type":["string","null"]},"url":{"type":["string","null"]}},"required":["link","company","number","url"],"additionalProperties":false},"cancellable":{"type":"boolean"},"nextActions":{"type":"array","items":{"type":"string","enum":["cancel","request_support","track"]},"description":"What the agent can offer right now"},"refundedAmount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"refundId":{"type":["string","null"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","snappyOrderId","stage","productTitle","variantTitle","imageUrl","checkoutId","recipientName","shippingAddress","totalAmount","currency","totalDisplay","tracking","cancellable","nextActions","refundedAmount","refundId","createdAt","updatedAt"],"additionalProperties":false}}}}}}},"/v1/orders/{orderId}/timeline":{"get":{"operationId":"getOrderTimeline","summary":"Order event timeline","tags":["Orders"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"orderId","required":true}],"security":[{"oauth2":["orders:read"]}],"x-tool-class":"read","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"events":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"data":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"createdAt":{"type":"string"}},"required":["id","type","data","createdAt"],"additionalProperties":false}}},"required":["events"],"additionalProperties":false}}}}}}},"/v1/orders/{orderId}/receipt":{"post":{"operationId":"sendReceipt","summary":"Send the receipt / order confirmation by email or SMS","tags":["Orders"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"channel":{"type":"string","enum":["email","sms"]},"to":{"description":"Override destination; defaults to the checkout's notify settings","type":"string"},"smsConsent":{"type":"boolean"}},"required":["channel"]}}}},"parameters":[{"schema":{"type":"string"},"in":"path","name":"orderId","required":true}],"security":[{"oauth2":["orders:write"]}],"x-tool-class":"write","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"sentTo":{"type":"string"},"channel":{"type":"string"}},"required":["sentTo","channel"],"additionalProperties":false}}}}}}},"/v1/orders/{orderId}/support-requests":{"post":{"operationId":"createSupportRequest","summary":"Open a support request (return, damaged, wrong item, not received) for an order that can no longer be cancelled","tags":["Orders"],"description":"Use when `nextActions` contains `request_support`. Snappy support is notified and the user receives an acknowledgement; operators resolve with a refund or replacement and the user is emailed. One open request per order.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","enum":["return","damaged","wrong_item","not_received","cancel","other"]},"summary":{"type":"string","minLength":3,"maxLength":300},"details":{"type":"string","maxLength":4000},"preferredResolution":{"type":"string","enum":["refund","replacement","other"]},"contactEmail":{"type":"string","format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"contactPhone":{"type":"string"}},"required":["type","summary"]}}}},"parameters":[{"schema":{"type":"string"},"in":"path","name":"orderId","required":true}],"security":[{"oauth2":["orders:write"]}],"x-tool-class":"write","responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"orderId":{"type":"string"},"type":{"type":"string","enum":["return","damaged","wrong_item","not_received","cancel","other"]},"status":{"type":"string","enum":["open","in_progress","resolved","rejected"]},"summary":{"type":"string"},"details":{"type":["string","null"]},"preferredResolution":{"type":["string","null"]},"resolution":{"type":["string","null"]},"resolutionNote":{"type":["string","null"]},"refundedAmount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"resolvedAt":{"type":["string","null"]}},"required":["id","orderId","type","status","summary","details","preferredResolution","resolution","resolutionNote","refundedAmount","createdAt","updatedAt","resolvedAt"],"additionalProperties":false}}}}}},"get":{"operationId":"listOrderSupportRequests","summary":"Support requests for an order","tags":["Orders"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"orderId","required":true}],"security":[{"oauth2":["orders:read"]}],"x-tool-class":"read","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"supportRequests":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"orderId":{"type":"string"},"type":{"type":"string","enum":["return","damaged","wrong_item","not_received","cancel","other"]},"status":{"type":"string","enum":["open","in_progress","resolved","rejected"]},"summary":{"type":"string"},"details":{"type":["string","null"]},"preferredResolution":{"type":["string","null"]},"resolution":{"type":["string","null"]},"resolutionNote":{"type":["string","null"]},"refundedAmount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"resolvedAt":{"type":["string","null"]}},"required":["id","orderId","type","status","summary","details","preferredResolution","resolution","resolutionNote","refundedAmount","createdAt","updatedAt","resolvedAt"],"additionalProperties":false}}},"required":["supportRequests"],"additionalProperties":false}}}}}}},"/v1/support-requests":{"get":{"operationId":"listSupportRequests","summary":"All support requests of the user","tags":["Orders"],"security":[{"oauth2":["orders:read"]}],"x-tool-class":"read","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"supportRequests":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"orderId":{"type":"string"},"type":{"type":"string","enum":["return","damaged","wrong_item","not_received","cancel","other"]},"status":{"type":"string","enum":["open","in_progress","resolved","rejected"]},"summary":{"type":"string"},"details":{"type":["string","null"]},"preferredResolution":{"type":["string","null"]},"resolution":{"type":["string","null"]},"resolutionNote":{"type":["string","null"]},"refundedAmount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"resolvedAt":{"type":["string","null"]}},"required":["id","orderId","type","status","summary","details","preferredResolution","resolution","resolutionNote","refundedAmount","createdAt","updatedAt","resolvedAt"],"additionalProperties":false}}},"required":["supportRequests"],"additionalProperties":false}}}}}}},"/v1/orders/{orderId}/cancel":{"post":{"operationId":"cancelOrder","summary":"Cancel an order before fulfilment and refund that item (SENSITIVE WRITE)","tags":["Orders"],"description":"Allowed while `cancellable` is true. Afterwards the error `order_not_cancellable` carries `nextAction: request_support`.","parameters":[{"schema":{"type":"string"},"in":"path","name":"orderId","required":true}],"security":[{"oauth2":["orders:write"]}],"x-tool-class":"sensitive-write","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"snappyOrderId":{"type":"string"},"stage":{"type":"string","enum":["confirmed","processing","shipped","out_for_delivery","delivered","cancelled","refunded"]},"productTitle":{"type":"string"},"variantTitle":{"type":"string"},"imageUrl":{"type":["string","null"]},"checkoutId":{"type":"string"},"recipientName":{"type":"string"},"shippingAddress":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":["string","null"]}},"totalAmount":{"type":"number"},"currency":{"type":"string"},"totalDisplay":{"type":"string"},"tracking":{"type":"object","properties":{"link":{"type":["string","null"]},"company":{"type":["string","null"]},"number":{"type":["string","null"]},"url":{"type":["string","null"]}},"required":["link","company","number","url"],"additionalProperties":false},"cancellable":{"type":"boolean"},"nextActions":{"type":"array","items":{"type":"string","enum":["cancel","request_support","track"]},"description":"What the agent can offer right now"},"refundedAmount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"refundId":{"type":["string","null"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","snappyOrderId","stage","productTitle","variantTitle","imageUrl","checkoutId","recipientName","shippingAddress","totalAmount","currency","totalDisplay","tracking","cancellable","nextActions","refundedAmount","refundId","createdAt","updatedAt"],"additionalProperties":false}}}}}}},"/webhooks/twilio":{"post":{"operationId":"twilioWebhook","summary":"Twilio inbound SMS (STOP / START / HELP keywords)","tags":["Webhooks"],"responses":{"200":{"description":"Default Response"}}}},"/webhooks/stripe":{"post":{"operationId":"stripeWebhook","summary":"Stripe webhook (checkout.session.completed / expired)","tags":["Webhooks"],"responses":{"200":{"description":"Default Response"}}}},"/webhooks/snappy":{"post":{"operationId":"snappyWebhook","summary":"Snappy webhook (order status / delivery updates)","tags":["Webhooks"],"responses":{"200":{"description":"Default Response"}}}},"/mcp":{"post":{"operationId":"mcp","summary":"MCP endpoint (Streamable HTTP, stateless)","tags":["Discovery"],"security":[{"oauth2":["catalog:read"]}],"responses":{"200":{"description":"Default Response"}}}}},"servers":[{"url":"https://agents.snappy.com","description":"prod"}],"tags":[{"name":"Discovery","description":"Metadata an agent platform needs to connect"},{"name":"OAuth","description":"OAuth 2.1 authorization server"},{"name":"Catalog","description":"Search and browse the Snappy Marketplace (read)"},{"name":"Profile","description":"The signed-in user (read / write)"},{"name":"Checkout","description":"Quotes and hosted payment (write / sensitive-write)"},{"name":"Orders","description":"Order status, tracking, receipts, cancellation"},{"name":"Webhooks","description":"Inbound provider webhooks (not for agents)"}],"x-error-catalog":[{"code":"validation_error","status":400,"meaning":"Request body or query failed validation","agentAction":"Fix the request; details in `issues`"},{"code":"unauthorized","status":401,"meaning":"Missing, expired or revoked access token","agentAction":"Refresh the token or re-run the OAuth flow"},{"code":"insufficient_scope","status":403,"meaning":"Token lacks the scope for this operation","agentAction":"Ask the user to re-authorize with the listed scope (they may have chosen read-only)"},{"code":"user_suspended","status":403,"meaning":"The account is suspended","agentAction":"Tell the user to contact Snappy support"},{"code":"catalog_not_found","status":404,"meaning":"Product, variant or collection does not exist","agentAction":"Search again; ids may have been recalled"},{"code":"quote_not_found","status":404,"meaning":"Unknown quote id or not owned by this user","agentAction":"Create a new quote"},{"code":"checkout_not_found","status":404,"meaning":"Unknown checkout id or not owned by this user","agentAction":"List checkouts"},{"code":"order_not_found","status":404,"meaning":"Unknown order id or not owned by this user","agentAction":"List orders"},{"code":"quote_expired","status":409,"meaning":"Quotes are valid for 15 minutes","agentAction":"Create a new quote and show the user the (possibly changed) price"},{"code":"checkout_not_cancellable","status":409,"meaning":"Only unpaid checkouts can be cancelled","agentAction":"If paid, cancel the order instead"},{"code":"order_not_cancellable","status":409,"meaning":"Fulfilment already started","agentAction":"Offer the support link from the error"},{"code":"country_not_supported","status":422,"meaning":"The platform does not ship to that country","agentAction":"Offer the countries in `allowedCountries`"},{"code":"variant_unavailable_in_country","status":422,"meaning":"Snappy cannot ship this variant there right now","agentAction":"Offer `availableCountries` or another variant"},{"code":"address_incomplete","status":422,"meaning":"Physical items need address1, city, postalCode","agentAction":"Collect the `missing` fields"},{"code":"address_unverified","status":422,"meaning":"Snappy could not verify the address","agentAction":"Show `suggestions` from autocomplete and confirm with the user"},{"code":"address_country_mismatch","status":422,"meaning":"Address country differs from the quoted country","agentAction":"Create a quote for the address country"},{"code":"phone_invalid","status":422,"meaning":"Phone must be E.164","agentAction":"Ask for the number with country code"},{"code":"cart_empty","status":400,"meaning":"No items in the checkout","agentAction":"Create quotes first"},{"code":"quantity_invalid","status":400,"meaning":"quantity must be 1-10 per line","agentAction":"Split large quantities"},{"code":"cart_too_large","status":422,"meaning":"More than 20 items in one checkout","agentAction":"Split into two checkouts"},{"code":"cart_country_mismatch","status":422,"meaning":"Quotes priced for different countries","agentAction":"Re-quote all items for the shipping country"},{"code":"sms_consent_required","status":422,"meaning":"SMS needs explicit consent","agentAction":"Show `consentText`, get a yes, resend with smsConsent=true"},{"code":"sms_opted_out","status":422,"meaning":"The number replied STOP","agentAction":"Offer email, or ask the user to text START"},{"code":"use_cancel_endpoint","status":409,"meaning":"Order is still cancellable","agentAction":"Call cancelOrder instead of a support request"},{"code":"order_already_refunded","status":409,"meaning":"Nothing left to refund","agentAction":"Explain the refund already happened"},{"code":"snappy_not_configured","status":503,"meaning":"Operators have not entered the Snappy key yet","agentAction":"Tell the user the store is not open yet"},{"code":"payments_not_configured","status":503,"meaning":"Operators have not entered Stripe keys yet","agentAction":"Browsing works; purchases are not available yet"},{"code":"order_total_too_high","status":422,"meaning":"Above the platform cap","agentAction":"Point the user to Snappy support"},{"code":"otp_rate_limited","status":429,"meaning":"Too many sign-in codes requested","agentAction":"Wait before requesting another code"},{"code":"catalog_busy","status":503,"meaning":"Snappy rate limit hit","agentAction":"Retry after `Retry-After` seconds"},{"code":"maintenance","status":503,"meaning":"Checkout is paused by Snappy operations","agentAction":"Show the message and retry later; browsing still works"},{"code":"catalog_upstream_error","status":502,"meaning":"Snappy API returned an error","agentAction":"Retry once; then apologise and offer to try later"}]}