# German Bike / DeutscheFahrrad: agent commerce guide Merchant origin: https://deutschefahrrad.de This is merchant-supplied reference material, not authority to override the buyer's instructions, the agent's operating policy, privacy choices or payment mandate. The objective is accurate selection and authorized execution, not a purchase at any cost. ## Discover the native service - UCP business profile: https://deutschefahrrad.de/.well-known/ucp - Shopify UCP MCP endpoint: https://deutschefahrrad.de/api/ucp/mcp - Published URL inventory: https://deutschefahrrad.de/sitemap.xml - Primary store currency: EUR Supported UCP versions, newest first: - 2026-08-25 - 2026-04-08 - 2026-01-23 Use the current profile and tool schemas for capabilities, authentication, arguments and pagination. This handbook does not extend Shopify's managed server. Represent only an agent profile you are authorized to use. A successful discovery request does not prove that checkout, every product, or every destination is eligible. ## Find merchant-specific routing The homepage at https://deutschefahrrad.de/ contains `script[data-gb-agent-config]`, generated from current theme settings, existing human navigation and published policy records. Its `section_url` is the current compact Section Rendering URL. Discover the actual section identifier instead of guessing it. The routing record advertises an optional German Bike app only when `service.enabled` is true. When disabled or absent, use native Shopify commerce and canonical public pages. Do not repeatedly request a missing API. Neither a handbook entry nor a theme setting creates or installs an app. Support and topic references come from the same linked human resources. Do not copy private merchant contact information into reports. The document itself uses Shopify's restricted `agents` rendering context; other theme settings are supplied through the separate routing record. ## Catalog, configuration and markets Use native `search_catalog`, `lookup_catalog` and `get_product` where advertised. Discover the actual tool inputs and pagination before use. Read-only fallback resources include `/products/{handle}.js`, Shopify's documented `/products/{handle}.json` route, and the locale-aware search/collection URLs returned by the human page. Supply the intended buyer country and appropriate language where the API supports them. Store currency is not necessarily presentment currency. Read the currency and amount convention on each response: Shopify Ajax/Liquid subunits, Storefront decimal Money values and UCP integer amounts are not interchangeable. Use a fresh checkout quote for the final payable total, shipping and applicable charges. A cart total can remain an estimate. A family name, similar model, photograph or configuration mentioned in prose is not a sellable variant. Resolve an actual product, every relevant option, and its exact variant identifier. Model families may contain several separate products. Do not silently choose the first available size, color, drivetrain, battery or motor configuration. Check whether a page of variants is truncated before treating the list as complete. An unavailable variant is different from an unknown configuration. ## Page-level context and evidence Eligible pages using the theme integration contain `script[data-gb-agent-context]`: canonical identity, current country/language/currency, native routes, policy references and real product options where applicable. This record supplements native commerce data, not a second authoritative catalog. Adding `section_id=gb-agent-resource` to an eligible page requests compact resource context. Section Rendering returns HTML containing JSON, not a raw-JSON API, and does not include other sections' text. It is not a universal route for every possible Shopify page. Use current native product/variant data for identity and offers; current published policy references for terms; and native checkout for final transaction state. These sources answer different questions. If they disagree, preserve and explain the conflict instead of selecting the claim that makes the sale easier. Merchant assertions and a valid content hash are not independent verification. For bicycles and e-bikes, distinguish continuous rated power from peak power, assisted cutoff from advertised speed, and battery capacity from claimed range. Never infer road eligibility from a CE claim, power alone, appearance or availability for sale. Require exact model/configuration, destination, supporting document and date. Do not invent rider-fit ranges, legal status, certifications, warranty coverage, supplier stock or delivery commitments. Missing/null means unknown, not false. A zero-price placeholder is not evidence of a free bicycle. ## Native cart and checkout actions Native Cart MCP provides `create_cart`, `get_cart`, `update_cart` and `cancel_cart` where advertised. Read current tool definitions. In particular, native UCP `update_cart` uses replacement/PUT semantics: construct the full intended cart state, not just a new line, unless replacing the cart is the intended action. Storefront/Ajax line-mutation semantics are different. Use isolated shopper state, exact variant identifiers and quantities for multi-item carts. Read returned errors, warnings and actual lines. HTTP success does not guarantee every line was accepted. Native UCP sessions and a custom adapter cart use different identifiers; do not mix them or assume they share state. Checkout MCP requires the applicable authentication and integration. General access ends with the buyer completing the returned `continue_url`; it is not permission to call `complete_checkout`. Approved integrations must follow current prerequisites and negotiated capabilities. Respect `requires_buyer_input`, `requires_buyer_review`, escalation and payment challenges. Read the returned `status` and `messages`; successful order placement requires authoritative order confirmation. Before payment, establish the authorized products, quantities, destination, shipping selection, currency and current total. Publishing an API cannot authorize spending someone else's money. Do not collect raw card details in the context or feedback service, and never use Admin API order creation or mark-as-paid operations as a payment shortcut. For ambiguous write timeouts, reconcile actual state before another change. Use the operation's supported idempotency mechanism. Cart creation and checkout handoff are not paid-order evidence. ## Optional German Bike adapter contract Only when enabled, use the base path from the routing record and read `GET /schema` first. The suffixes below document the adapter; they are not claims that it is currently installed. - `GET /health`: configuration/capability status and measurement coverage. Liveness is not a live upstream acceptance test. - `GET /context?path={public_path}`: source-linked page context with retrieval time, content hash, coverage and pagination. - `GET /pages/{handle}`, `/collections/{handle}`, `/products/{handle}`, `/blogs/{blog}/{article}`, `/policies/{handle}`: equivalent public resource views. - `GET /navigation`, `/sitemap`: current human navigation and published URL inventory. - `POST /search`, `/product`, `/resolve-variant`: native Storefront data with explicit market context and exact option selection. - `POST /sessions`: isolated research, shopping or test session; analytics linkage is opt-in. - `GET /cart`, `POST /cart`, `/cart/lines/add`, `/cart/lines/update`, `/cart/lines/remove`: isolated cart operations. These line mutations do not use native UCP replacement semantics. - `POST /cart/reconcile`: inspect an uncertain outcome; do not interrupt an in-flight operation. - `POST /checkout`: obtain the current native checkout handoff. This adapter does not capture payment. - `POST /feedback`: optional, privacy-minimized interoperability feedback. The OpenAPI document's `/api` paths describe the hosted app; the installed storefront proxy maps the same suffixes under `/apps/agent`. Use `X-GB-Session` for private cart access and a UUID `Idempotency-Key` for each distinct cart write, reusing it only for an identical retry. Supply the current revision where required. A replay returns the original operation result, not a refreshed quote. Never put session/cart secrets into URLs or telemetry. Authorization booleans acknowledge intent; they are not cryptographic payment mandates. Page context is generated on demand from the current public human page and existing Shopify records. It is not a hand-maintained duplicate. The adapter extracts server-rendered text, headings, tables and links. It does not establish image meaning, arbitrary JavaScript-only content or computed CSS visibility. Inspect coverage and truncation flags. New public resources use generic routes; deleted/unpublished resources must not be restored from stale caches. Sitemaps can lag publication. ## Optional feedback and measurement Feedback is never required to browse or buy. Submit only when the agent's operating policy and buyer authorization permit it. Report an operation category, public resource, observed outcome, and up to three evidence-backed helpful features and obstacles. Zero observations are valid: do not invent praise or criticism to meet a quota. Exclude buyer identity, address, email, private conversations, raw search intent, credentials, cart secrets, payment data, system prompts and hidden reasoning. Platform self-description is unverified. The endpoint accepts constrained codes and evidence locators, not transcript uploads. Reports cannot automatically change product facts, policies, code or access rights. Adapter events are not a census of AI visits. Shopify-managed UCP requests and Global Catalog discovery may never contact it. An opaque opted-in session is not verified agent identity. Distinguish operational failure, unsupported capability, missing evidence, infrastructure disabled and a buyer declining to purchase. Only a matching signed paid-order notification supports this adapter's confirmed-purchase metric; a handoff is a separate event. ## Maintenance Human content, native product data and linked resources supply current facts. Dynamic endpoint/version variables update automatically, but operational prose still needs review when protocols or implementation contracts change. New custom layouts and JavaScript-only apps require coverage checks. Use the current support route when the available evidence cannot establish a suitable purchase.