Vintagebulk API & AI-agent documentation

Vintagebulk is a Dutch B2B wholesale supplier of graded second-hand branded clothing (Ralph Lauren, Tommy Hilfiger, Carhartt, Nike, The North Face and more), sold in boxes and bales to resellers. This page documents the Vintagebulk API for developers and AI agents.

Machine-readable resources

OpenAPI 3.1 spec (JSON): /openapi.json · YAML: /openapi.yaml
Agent instructions (when to use Vintagebulk): /agents.md · /llms.txt
UCP merchant profile: /.well-known/ucp
MCP endpoint (JSON-RPC 2.0): POST https://vintagebulk.nl/api/ucp/mcp
OAuth metadata: authorization server · protected resource (RFC 9728)
Sitemap: /sitemap.xml

Quick start (no API key)

curl https://vintagebulk.nl/products.json?limit=5
curl https://vintagebulk.nl/products/adidas-schoenen-box.json
curl https://vintagebulk.nl/collections/best-sellers/products.json
curl "https://vintagebulk.nl/search/suggest.json?q=ralph+lauren&resources%5Btype%5D=product"
curl -X POST https://vintagebulk.nl/api/ucp/mcp -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Authentication and scopes

Catalog, search and cart endpoints need no authentication. Buyer-linked actions use Shopify Customer Account OAuth 2.0 (authorization code with PKCE S256). Request only the scopes you need:

dev.ucp.shopping.catalog.search:read – search the catalog for the buyer
dev.ucp.shopping.checkout:manage – create and complete checkouts (payment always needs explicit buyer approval)
customer-account-mcp-api:full – the buyer's orders and addresses via MCP
openid, email – identify the buyer

Errors

JSON endpoints return structured errors, for example {"status":422,"message":"Cart Error","description":"Cannot find variant"}. The MCP endpoint returns JSON-RPC error objects such as {"code":-32600,"message":"Invalid Request"}. On HTTP 429, back off exponentially.

MCP tools

search_catalog, lookup_catalog, get_product, create_cart, get_cart, update_cart, cancel_cart, create_checkout, get_checkout, update_checkout, complete_checkout, cancel_checkout, get_order. Call tools/list for full JSON schemas.

Testing

The live shop has no sandbox mode. All read-only endpoints are safe to call. To build and test cart and checkout flows without placing real orders, use mock.shop, a free mock Shopify Storefront API.