Developers & AI agents

Information for developers and AI agents that want to read our catalogue or help a customer order a custom printed flag. Everything below is public: no API key, no account and no sign-up needed.

Start here

• /agents.md – agent guide: when to use this shop, key facts, how to order
• /openapi.json – OpenAPI 3.1 description of the public endpoints
• /.well-known/ucp – Universal Commerce Protocol profile; MCP endpoint POST /api/ucp/mcp
• /sitemap.xml – all pages

Public endpoints

• GET /products.json?limit=250 – all products, variants and prices (EUR incl. VAT)
• GET /products/{handle}.json – one product
• GET /collections/{vlaggen|beachflags|accessoires}/products.json – products per collection
• GET /search/suggest.json?q=beachflag&resources[type]=product – search
• GET /cart.js, POST /cart/add.js, POST /cart/change.js – session cart

Errors are JSON, for example {"status":422,"message":"Cart Error","description":"Cannot find variant"}. On HTTP 429, back off and retry later. Use /de, /fr, /es, /it or /nl on www.buildyourflag.com for translated content.

Ordering for a customer

Printed products need a design made in the design tool on the product page, so send the customer there. Accessories can be added to a cart directly. Checkout always needs the customer’s approval of the payment.

Signed-in customers (OAuth 2.0)

Order history and addresses go through the Shopify Customer Account API with OAuth 2.0 (authorization code with PKCE). Discovery: /.well-known/openid-configuration. Request only the scopes you need: dev.ucp.shopping.catalog.search:read, dev.ucp.shopping.checkout:manage, openid, email, customer-account-api:full.

Contact

Questions about integrations: contact page. About us: our story.