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

Versioned API

For a stable contract use the Storefront GraphQL API, no key needed: POST /api/2026-10/graphql.json with {"query":"{ products(first: 5) { nodes { handle title priceRange { minVariantPrice { amount currencyCode } } } } }"}. The version (YYYY-MM, quarterly) is in the path and each stable version is supported for at least 12 months. Every response names the version that ran in X-Shopify-API-Version; a version close to retirement adds X-Shopify-API-Version-Warning, and deprecated fields trigger X-Shopify-API-Deprecated-Reason. Errors are JSON with a code, for example {"errors":[{"message":"…","extensions":{"code":"undefinedField"}}]}. Policy: shopify.dev/docs/api/usage/versioning. The .json endpoints above are unversioned.

Prices of every product in a collection are also in the JSON-LD of /pricing.

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.