{
    "openapi": "3.1.0",
    "info": {
        "title": "glasstopfen.de UCP Shopping REST",
        "version": "0.6.2",
        "termsOfService": "https://glasstopfen.de/legal/agb",
        "x-glasstopfen-limits": {
            "max_quantity_per_line_item": 3,
            "max_quantity_per_checkout": 5,
            "error": "quantity_limit_exceeded"
        },
        "description": "UCP 2026-08-25 REST binding of glasstopfen.de (same paths as https://ucp.dev/2026-08-25/services/shopping/rest.openapi.json). Discovery: https://glasstopfen.de/.well-known/ucp. The same operations are offered as MCP tools at https://glasstopfen.de/mcp."
    },
    "servers": [
        {
            "url": "https://glasstopfen.de/ucp/v1",
            "description": "Live"
        },
        {
            "url": "https://glasstopfen.de/ucp/sandbox/v1",
            "description": "Sandbox (test mode): no real order, no stock reservation, no e-mail, ids with test_, example bank data. Alternative: header UCP-Sandbox: true on /ucp/v1."
        }
    ],
    "x-glasstopfen-sandbox": {
        "enabled": true,
        "purpose": "Test mode for agents: play through cart, checkout (create, update, complete), get order and withdrawal without a real order. Same request and response shapes, validation and error codes as the live API.",
        "rest": "https://glasstopfen.de/ucp/sandbox/v1",
        "rest_header_alias": "Send UCP-Sandbox: true to https://glasstopfen.de/ucp/v1/... to reach the same sandbox.",
        "mcp": "https://glasstopfen.de/mcp/sandbox",
        "marker": "Every sandbox response carries the header UCP-Sandbox: true and the body field de.glasstopfen.sandbox.",
        "guarantees": [
            "No order is created in the shop, no stock is reserved, nothing is charged.",
            "No e-mail is sent to anybody (withdrawal confirmation: not_sent_sandbox).",
            "All ids start with test_ (test_chk_, test_crt_, test_ord_, test_ot_, test_wrq_, test_wdr_); order numbers look like TEST-123456.",
            "Bank details are examples (account holder SANDBOX EXAMPLE - DO NOT PAY, IBAN DE50000000000123456789, BIC TESTDEFFXXX). Never show them as real payment details."
        ],
        "catalog": "Catalog reads (search, lookup, product, vehicle fit) and prices are real and read-only.",
        "payment": "Only bank_transfer is simulated (EUR); card payment is not simulated.",
        "session_ttl_seconds": 86400,
        "rate_limits": {
            "per_minute": 30,
            "per_hour": 300,
            "scope": "per client IP",
            "error": "429 rate_limited with Retry-After"
        }
    },
    "x-glasstopfen-repair": {
        "overview": "https://glasstopfen.de/repair",
        "part_number_lookup": "https://glasstopfen.de/repair/part/{part_number}?country=DE",
        "mcp_tool": "find_by_wiper_motor_part_number",
        "note": "The repair lookup is served outside /ucp/v1 (read-only JSON); this document stays the UCP REST surface only.",
        "search_by_part_number": "POST /catalog/search with {\"query\": \"<wiper motor part number>\"} or filters.part_number returns the matching plug set plus de.glasstopfen.repair_match"
    },
    "externalDocs": {
        "description": "Legal pages (German, in force since 2026-11-14): terms, withdrawal, privacy, legal notice",
        "url": "https://glasstopfen.de/legal/"
    },
    "x-glasstopfen-legal": {
        "draft": false,
        "status": "in Kraft (freigegeben am 14.11.2026)",
        "status_en": "in force (approved on 14 November 2026)",
        "in_force_since": "2026-11-14",
        "languages": [
            "de"
        ],
        "english_version": "not available yet",
        "pages": [
            {
                "id": "impressum",
                "type": "legal_notice",
                "title": "Impressum",
                "title_en": "Legal notice (imprint)",
                "language": "de",
                "draft": false,
                "url": "https://glasstopfen.de/legal/impressum",
                "markdown": "https://glasstopfen.de/legal/impressum.md",
                "json": "https://glasstopfen.de/legal/impressum.json"
            },
            {
                "id": "agb",
                "type": "terms_of_service",
                "title": "Allgemeine Geschäftsbedingungen und Kundeninformationen",
                "title_en": "Terms of sale and customer information",
                "language": "de",
                "draft": false,
                "url": "https://glasstopfen.de/legal/agb",
                "markdown": "https://glasstopfen.de/legal/agb.md",
                "json": "https://glasstopfen.de/legal/agb.json"
            },
            {
                "id": "widerruf",
                "type": "refund_policy",
                "title": "Widerrufsbelehrung und Muster-Widerrufsformular",
                "title_en": "Right of withdrawal and model withdrawal form",
                "language": "de",
                "draft": false,
                "url": "https://glasstopfen.de/legal/widerruf",
                "markdown": "https://glasstopfen.de/legal/widerruf.md",
                "json": "https://glasstopfen.de/legal/widerruf.json"
            },
            {
                "id": "datenschutz",
                "type": "privacy_policy",
                "title": "Datenschutzerklärung",
                "title_en": "Privacy policy",
                "language": "de",
                "draft": false,
                "url": "https://glasstopfen.de/legal/datenschutz",
                "markdown": "https://glasstopfen.de/legal/datenschutz.md",
                "json": "https://glasstopfen.de/legal/datenschutz.json"
            }
        ]
    },
    "paths": {
        "/catalog/search": {
            "post": {
                "operationId": "search_catalog",
                "summary": "Search the catalog",
                "description": "Available. Vehicle filter: filters.vehicle = {\"make\": string, \"model\": string, \"year\": integer} (glasstopfen addition inside the open UCP filters object). Rear wiper motor part number: query = \"<part number>\" or filters.part_number returns the matching plug set and de.glasstopfen.repair_match (vehicles, sources, uncertain flags). Destination country: context.address_country (ISO 3166-1 alpha-2) or a shipping address; without it prices are EUR estimates (warning country_required_for_final_price). USD is never a fallback.",
                "x-glasstopfen-availability": "available",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/ucp_agent"
                    },
                    {
                        "$ref": "#/components/parameters/request_id"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "UCP response or UCP error_response (business outcome)",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "oneOf": [
                                        {
                                            "$ref": "https://ucp.dev/2026-08-25/schemas/shopping/catalog_search.json#/$defs/search_response"
                                        },
                                        {
                                            "$ref": "https://ucp.dev/2026-08-25/schemas/common/types/error_response.json"
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/protocol_error"
                    },
                    "401": {
                        "$ref": "#/components/responses/protocol_error"
                    },
                    "409": {
                        "$ref": "#/components/responses/protocol_error"
                    },
                    "429": {
                        "$ref": "#/components/responses/retryable_error"
                    },
                    "503": {
                        "$ref": "#/components/responses/retryable_error"
                    }
                },
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "https://ucp.dev/2026-08-25/schemas/shopping/catalog_search.json#/$defs/search_request"
                            }
                        }
                    }
                }
            }
        },
        "/catalog/lookup": {
            "post": {
                "operationId": "lookup_catalog",
                "summary": "Look up products/variants by id",
                "description": "Available. Destination country: context.address_country (ISO 3166-1 alpha-2) or a shipping address; without it prices are EUR estimates (warning country_required_for_final_price). USD is never a fallback.",
                "x-glasstopfen-availability": "available",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/ucp_agent"
                    },
                    {
                        "$ref": "#/components/parameters/request_id"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "UCP response or UCP error_response (business outcome)",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "oneOf": [
                                        {
                                            "$ref": "https://ucp.dev/2026-08-25/schemas/shopping/catalog_lookup.json#/$defs/lookup_response"
                                        },
                                        {
                                            "$ref": "https://ucp.dev/2026-08-25/schemas/common/types/error_response.json"
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/protocol_error"
                    },
                    "401": {
                        "$ref": "#/components/responses/protocol_error"
                    },
                    "409": {
                        "$ref": "#/components/responses/protocol_error"
                    },
                    "429": {
                        "$ref": "#/components/responses/retryable_error"
                    },
                    "503": {
                        "$ref": "#/components/responses/retryable_error"
                    }
                },
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "https://ucp.dev/2026-08-25/schemas/shopping/catalog_lookup.json#/$defs/lookup_request"
                            }
                        }
                    }
                }
            }
        },
        "/catalog/product": {
            "post": {
                "operationId": "get_product",
                "summary": "Get one product",
                "description": "Available. Destination country: context.address_country (ISO 3166-1 alpha-2) or a shipping address; without it prices are EUR estimates (warning country_required_for_final_price). USD is never a fallback.",
                "x-glasstopfen-availability": "available",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/ucp_agent"
                    },
                    {
                        "$ref": "#/components/parameters/request_id"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "UCP response or UCP error_response (business outcome)",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "oneOf": [
                                        {
                                            "$ref": "https://ucp.dev/2026-08-25/schemas/shopping/catalog_lookup.json#/$defs/get_product_response"
                                        },
                                        {
                                            "$ref": "https://ucp.dev/2026-08-25/schemas/common/types/error_response.json"
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/protocol_error"
                    },
                    "401": {
                        "$ref": "#/components/responses/protocol_error"
                    },
                    "409": {
                        "$ref": "#/components/responses/protocol_error"
                    },
                    "429": {
                        "$ref": "#/components/responses/retryable_error"
                    },
                    "503": {
                        "$ref": "#/components/responses/retryable_error"
                    }
                },
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "https://ucp.dev/2026-08-25/schemas/shopping/catalog_lookup.json#/$defs/get_product_request"
                            }
                        }
                    }
                }
            }
        },
        "/carts": {
            "post": {
                "operationId": "create_cart",
                "summary": "Create a cart",
                "description": "Available. Destination country: context.address_country (ISO 3166-1 alpha-2) or a shipping address; without it prices are EUR estimates (warning country_required_for_final_price). USD is never a fallback.",
                "x-glasstopfen-availability": "available",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/ucp_agent"
                    },
                    {
                        "$ref": "#/components/parameters/request_id"
                    },
                    {
                        "$ref": "#/components/parameters/idempotency_key"
                    }
                ],
                "responses": {
                    "201": {
                        "description": "UCP response or UCP error_response (business outcome)",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "oneOf": [
                                        {
                                            "$ref": "https://ucp.dev/2026-08-25/schemas/shopping/cart.json"
                                        },
                                        {
                                            "$ref": "https://ucp.dev/2026-08-25/schemas/common/types/error_response.json"
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/protocol_error"
                    },
                    "401": {
                        "$ref": "#/components/responses/protocol_error"
                    },
                    "409": {
                        "$ref": "#/components/responses/protocol_error"
                    },
                    "429": {
                        "$ref": "#/components/responses/retryable_error"
                    },
                    "503": {
                        "$ref": "#/components/responses/retryable_error"
                    }
                },
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "https://ucp.dev/2026-08-25/schemas/shopping/cart.json"
                            }
                        }
                    }
                }
            }
        },
        "/carts/{id}": {
            "get": {
                "operationId": "get_cart",
                "summary": "Get a cart",
                "description": "Available.",
                "x-glasstopfen-availability": "available",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/ucp_agent"
                    },
                    {
                        "$ref": "#/components/parameters/request_id"
                    },
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "pattern": "^[A-Za-z0-9_-]{1,64}$"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "UCP response or UCP error_response (business outcome)",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "oneOf": [
                                        {
                                            "$ref": "https://ucp.dev/2026-08-25/schemas/shopping/cart.json"
                                        },
                                        {
                                            "$ref": "https://ucp.dev/2026-08-25/schemas/common/types/error_response.json"
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/protocol_error"
                    },
                    "401": {
                        "$ref": "#/components/responses/protocol_error"
                    },
                    "409": {
                        "$ref": "#/components/responses/protocol_error"
                    },
                    "429": {
                        "$ref": "#/components/responses/retryable_error"
                    },
                    "503": {
                        "$ref": "#/components/responses/retryable_error"
                    }
                }
            },
            "put": {
                "operationId": "update_cart",
                "summary": "Update a cart (full replacement of line items)",
                "description": "Available.",
                "x-glasstopfen-availability": "available",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/ucp_agent"
                    },
                    {
                        "$ref": "#/components/parameters/request_id"
                    },
                    {
                        "$ref": "#/components/parameters/idempotency_key"
                    },
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "pattern": "^[A-Za-z0-9_-]{1,64}$"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "UCP response or UCP error_response (business outcome)",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "oneOf": [
                                        {
                                            "$ref": "https://ucp.dev/2026-08-25/schemas/shopping/cart.json"
                                        },
                                        {
                                            "$ref": "https://ucp.dev/2026-08-25/schemas/common/types/error_response.json"
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/protocol_error"
                    },
                    "401": {
                        "$ref": "#/components/responses/protocol_error"
                    },
                    "409": {
                        "$ref": "#/components/responses/protocol_error"
                    },
                    "429": {
                        "$ref": "#/components/responses/retryable_error"
                    },
                    "503": {
                        "$ref": "#/components/responses/retryable_error"
                    }
                },
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "https://ucp.dev/2026-08-25/schemas/shopping/cart.json"
                            }
                        }
                    }
                }
            }
        },
        "/carts/{id}/cancel": {
            "post": {
                "operationId": "cancel_cart",
                "summary": "Cancel a cart",
                "description": "Available.",
                "x-glasstopfen-availability": "available",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/ucp_agent"
                    },
                    {
                        "$ref": "#/components/parameters/request_id"
                    },
                    {
                        "$ref": "#/components/parameters/idempotency_key"
                    },
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "pattern": "^[A-Za-z0-9_-]{1,64}$"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "UCP response or UCP error_response (business outcome)",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "oneOf": [
                                        {
                                            "$ref": "https://ucp.dev/2026-08-25/schemas/shopping/cart.json"
                                        },
                                        {
                                            "$ref": "https://ucp.dev/2026-08-25/schemas/common/types/error_response.json"
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/protocol_error"
                    },
                    "401": {
                        "$ref": "#/components/responses/protocol_error"
                    },
                    "409": {
                        "$ref": "#/components/responses/protocol_error"
                    },
                    "429": {
                        "$ref": "#/components/responses/retryable_error"
                    },
                    "503": {
                        "$ref": "#/components/responses/retryable_error"
                    }
                }
            }
        },
        "/checkout-sessions": {
            "post": {
                "operationId": "create_checkout",
                "summary": "Create a checkout session",
                "description": "Available. Destination country: context.address_country (ISO 3166-1 alpha-2) or a shipping address; without it prices are EUR estimates (warning country_required_for_final_price). USD is never a fallback.",
                "x-glasstopfen-availability": "available",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/ucp_agent"
                    },
                    {
                        "$ref": "#/components/parameters/request_id"
                    },
                    {
                        "$ref": "#/components/parameters/idempotency_key"
                    }
                ],
                "responses": {
                    "201": {
                        "description": "UCP response or UCP error_response (business outcome)",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "oneOf": [
                                        {
                                            "$ref": "https://ucp.dev/2026-08-25/schemas/shopping/checkout.json"
                                        },
                                        {
                                            "$ref": "https://ucp.dev/2026-08-25/schemas/common/types/error_response.json"
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/protocol_error"
                    },
                    "401": {
                        "$ref": "#/components/responses/protocol_error"
                    },
                    "409": {
                        "$ref": "#/components/responses/protocol_error"
                    },
                    "429": {
                        "$ref": "#/components/responses/retryable_error"
                    },
                    "503": {
                        "$ref": "#/components/responses/retryable_error"
                    }
                },
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "https://ucp.dev/2026-08-25/schemas/shopping/checkout.json"
                            }
                        }
                    }
                }
            }
        },
        "/checkout-sessions/{id}": {
            "get": {
                "operationId": "get_checkout",
                "summary": "Get a checkout session",
                "description": "Available.",
                "x-glasstopfen-availability": "available",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/ucp_agent"
                    },
                    {
                        "$ref": "#/components/parameters/request_id"
                    },
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "pattern": "^[A-Za-z0-9_-]{1,64}$"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "UCP response or UCP error_response (business outcome)",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "oneOf": [
                                        {
                                            "$ref": "https://ucp.dev/2026-08-25/schemas/shopping/checkout.json"
                                        },
                                        {
                                            "$ref": "https://ucp.dev/2026-08-25/schemas/common/types/error_response.json"
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/protocol_error"
                    },
                    "401": {
                        "$ref": "#/components/responses/protocol_error"
                    },
                    "409": {
                        "$ref": "#/components/responses/protocol_error"
                    },
                    "429": {
                        "$ref": "#/components/responses/retryable_error"
                    },
                    "503": {
                        "$ref": "#/components/responses/retryable_error"
                    }
                }
            },
            "put": {
                "operationId": "update_checkout",
                "summary": "Update a checkout session",
                "description": "Available.",
                "x-glasstopfen-availability": "available",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/ucp_agent"
                    },
                    {
                        "$ref": "#/components/parameters/request_id"
                    },
                    {
                        "$ref": "#/components/parameters/idempotency_key"
                    },
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "pattern": "^[A-Za-z0-9_-]{1,64}$"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "UCP response or UCP error_response (business outcome)",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "oneOf": [
                                        {
                                            "$ref": "https://ucp.dev/2026-08-25/schemas/shopping/checkout.json"
                                        },
                                        {
                                            "$ref": "https://ucp.dev/2026-08-25/schemas/common/types/error_response.json"
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/protocol_error"
                    },
                    "401": {
                        "$ref": "#/components/responses/protocol_error"
                    },
                    "409": {
                        "$ref": "#/components/responses/protocol_error"
                    },
                    "429": {
                        "$ref": "#/components/responses/retryable_error"
                    },
                    "503": {
                        "$ref": "#/components/responses/retryable_error"
                    }
                },
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "https://ucp.dev/2026-08-25/schemas/shopping/checkout.json"
                            }
                        }
                    }
                }
            }
        },
        "/checkout-sessions/{id}/complete": {
            "post": {
                "operationId": "complete_checkout",
                "summary": "Complete the checkout (place the order; bank transfer: response carries de.glasstopfen.payment_instructions)",
                "description": "Available.",
                "x-glasstopfen-availability": "available",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/ucp_agent"
                    },
                    {
                        "$ref": "#/components/parameters/request_id"
                    },
                    {
                        "$ref": "#/components/parameters/idempotency_key"
                    },
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "pattern": "^[A-Za-z0-9_-]{1,64}$"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "UCP response or UCP error_response (business outcome)",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "oneOf": [
                                        {
                                            "$ref": "https://ucp.dev/2026-08-25/schemas/shopping/checkout.json"
                                        },
                                        {
                                            "$ref": "https://ucp.dev/2026-08-25/schemas/common/types/error_response.json"
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/protocol_error"
                    },
                    "401": {
                        "$ref": "#/components/responses/protocol_error"
                    },
                    "409": {
                        "$ref": "#/components/responses/protocol_error"
                    },
                    "429": {
                        "$ref": "#/components/responses/retryable_error"
                    },
                    "503": {
                        "$ref": "#/components/responses/retryable_error"
                    }
                },
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "https://ucp.dev/2026-08-25/schemas/shopping/checkout.json"
                            }
                        }
                    }
                }
            }
        },
        "/checkout-sessions/{id}/cancel": {
            "post": {
                "operationId": "cancel_checkout",
                "summary": "Cancel a checkout session",
                "description": "Available.",
                "x-glasstopfen-availability": "available",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/ucp_agent"
                    },
                    {
                        "$ref": "#/components/parameters/request_id"
                    },
                    {
                        "$ref": "#/components/parameters/idempotency_key"
                    },
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "pattern": "^[A-Za-z0-9_-]{1,64}$"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "UCP response or UCP error_response (business outcome)",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "oneOf": [
                                        {
                                            "$ref": "https://ucp.dev/2026-08-25/schemas/shopping/checkout.json"
                                        },
                                        {
                                            "$ref": "https://ucp.dev/2026-08-25/schemas/common/types/error_response.json"
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/protocol_error"
                    },
                    "401": {
                        "$ref": "#/components/responses/protocol_error"
                    },
                    "409": {
                        "$ref": "#/components/responses/protocol_error"
                    },
                    "429": {
                        "$ref": "#/components/responses/retryable_error"
                    },
                    "503": {
                        "$ref": "#/components/responses/retryable_error"
                    }
                }
            }
        },
        "/orders/{id}": {
            "get": {
                "operationId": "get_order",
                "summary": "Get an order (needs the order token from complete; on hold: de.glasstopfen.payment_instructions)",
                "description": "Available.",
                "x-glasstopfen-availability": "available",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/ucp_agent"
                    },
                    {
                        "$ref": "#/components/parameters/request_id"
                    },
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "pattern": "^[A-Za-z0-9_-]{1,64}$"
                        }
                    },
                    {
                        "$ref": "#/components/parameters/order_token"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "UCP response or UCP error_response (business outcome)",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "oneOf": [
                                        {
                                            "$ref": "https://ucp.dev/2026-08-25/schemas/shopping/order.json"
                                        },
                                        {
                                            "$ref": "https://ucp.dev/2026-08-25/schemas/common/types/error_response.json"
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/protocol_error"
                    },
                    "401": {
                        "$ref": "#/components/responses/protocol_error"
                    },
                    "409": {
                        "$ref": "#/components/responses/protocol_error"
                    },
                    "429": {
                        "$ref": "#/components/responses/retryable_error"
                    },
                    "503": {
                        "$ref": "#/components/responses/retryable_error"
                    }
                }
            }
        },
        "/withdrawals": {
            "post": {
                "operationId": "request_withdrawal",
                "x-glasstopfen-status": "enabled",
                "summary": "Request a withdrawal (step 1, nothing declared yet)",
                "description": "Paragraph 356a BGB. Body {order_id | order_number, buyer: {email, name?}, statement?}. Returns a request id (wrq_..., 30 min), summary and expires_at; the shop is not contacted yet. Not stopped when the operator pauses ordering.",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/request_id"
                    },
                    {
                        "$ref": "#/components/parameters/idempotency_key"
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "buyer"
                                ],
                                "properties": {
                                    "order_id": {
                                        "type": "string"
                                    },
                                    "order_number": {
                                        "type": "string"
                                    },
                                    "buyer": {
                                        "type": "object",
                                        "required": [
                                            "email"
                                        ],
                                        "properties": {
                                            "name": {
                                                "type": "string"
                                            },
                                            "email": {
                                                "type": "string",
                                                "format": "email"
                                            }
                                        }
                                    },
                                    "statement": {
                                        "type": "string",
                                        "maxLength": 1000
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Withdrawal prepared (status pending_confirmation) or business error withdrawal_not_possible",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/protocol_error"
                    },
                    "409": {
                        "$ref": "#/components/responses/protocol_error"
                    },
                    "503": {
                        "$ref": "#/components/responses/retryable_error"
                    }
                }
            }
        },
        "/withdrawals/{id}/confirm": {
            "post": {
                "operationId": "confirm_withdrawal",
                "x-glasstopfen-status": "enabled",
                "summary": "Declare the withdrawal (step 2, after explicit buyer confirmation)",
                "description": "Body {\"confirm\": true}. Sends the withdrawal to the shop; returns the reference (wdr_...), status received and received_at (receipt confirmation).",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/request_id"
                    },
                    {
                        "$ref": "#/components/parameters/idempotency_key"
                    },
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "pattern": "^wrq_[0-9A-Z]{10,30}$"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "confirm"
                                ],
                                "properties": {
                                    "confirm": {
                                        "type": "boolean",
                                        "const": true
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Withdrawal received (status received) or business error withdrawal_expired",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/protocol_error"
                    },
                    "409": {
                        "$ref": "#/components/responses/protocol_error"
                    },
                    "503": {
                        "$ref": "#/components/responses/retryable_error"
                    }
                }
            }
        }
    },
    "components": {
        "parameters": {
            "ucp_agent": {
                "name": "UCP-Agent",
                "in": "header",
                "required": false,
                "schema": {
                    "type": "string"
                },
                "description": "RFC 8941 dictionary with the platform profile, e.g. profile=\"https://platform.example/.well-known/ucp\". Recommended; v0 records it as claimed identity and does not fetch it."
            },
            "request_id": {
                "name": "Request-Id",
                "in": "header",
                "required": false,
                "schema": {
                    "type": "string"
                },
                "description": "Tracing id; generated when absent and echoed in the response."
            },
            "idempotency_key": {
                "name": "Idempotency-Key",
                "in": "header",
                "required": true,
                "schema": {
                    "type": "string",
                    "format": "uuid"
                },
                "description": "Required for every write. Same key + same body returns the original result; same key + different body returns 409 idempotency_conflict."
            },
            "order_token": {
                "name": "Authorization",
                "in": "header",
                "required": true,
                "schema": {
                    "type": "string"
                },
                "description": "Bearer <order_token> returned by complete_checkout."
            }
        },
        "responses": {
            "protocol_error": {
                "description": "Protocol error",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/protocol_error"
                        }
                    }
                }
            },
            "retryable_error": {
                "description": "Retry later (see Retry-After)",
                "headers": {
                    "Retry-After": {
                        "schema": {
                            "type": "integer"
                        }
                    }
                },
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/protocol_error"
                        }
                    }
                }
            }
        },
        "schemas": {
            "protocol_error": {
                "type": "object",
                "required": [
                    "code",
                    "content"
                ],
                "properties": {
                    "code": {
                        "type": "string",
                        "enum": [
                            "temporarily_unavailable",
                            "rate_limited",
                            "idempotency_conflict",
                            "request_in_progress",
                            "idempotency_key_required",
                            "invalid_request",
                            "invalid_json",
                            "unauthorized",
                            "not_found",
                            "method_not_allowed",
                            "unsupported_media_type",
                            "withdrawal_unavailable",
                            "internal_error"
                        ]
                    },
                    "content": {
                        "type": "string"
                    }
                }
            }
        }
    }
}
